Subscribe to a webhook

warning

This is a V1 legacy endpoint. It uses a different path /rest/v1 and may return different error codes and response formats compared to V2. While it remains functional, consider handling errors accordingly.

Start receiving notifications for selected events via webhook. Whenever an event occurs, we will send the event data as an array of objects to the specified target URL.

Request

Endpoint

POST https://api.woodpecker.co/rest/v1/webhooks/subscribe

Headers

x-api-key: {YOUR_API_KEY}
Content-type: application/json

For details on how to authenticate your requests, please see the authentication guide.

Body

You can subscribe to the same event up to three times per account, provided that each subscription uses a unique target_url. However, you can subscribe multiple different events to a single target_url.

{ 
  "target_url": "https://receiving-url.com/unique_target_url",      
  "event": "EVENT_NAME" 
}

Body schema

Field	Type	Description
target_url	string	The URL where webhook events will be delivered
event	string	Event you would like to be notified about. Available events

Request sample

Subscribe to a webhook

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v1/webhooks/subscribe" \
  --header "Content-Type: application/json" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --data '{
    "target_url": "https://receiving-url.com/unique_target_url",
    "event": "EVENT_NAME"
  }'

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    String apiKey = "{YOUR_API_KEY}";
    String targetUrl = "https://receiving-url.com/unique_target_url";
    String event = "EVENT_NAME";

    String jsonPayload = String.format(
      "{\"target_url\": \"%s\", \"event\": \"%s\"}",
      targetUrl, event
    );

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.woodpecker.co/rest/v1/webhooks/subscribe"))
      .header("Content-Type", "application/json")
      .header("x-api-key", apiKey)
      .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
      .build();

    try {
      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println("Response status: " + response.statusCode());
      System.out.println("Response body: " + response.body());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

const apiKey = "{YOUR_API_KEY}";
const targetUrl = "https://receiving-url.com/unique_target_url";
const event = "EVENT_NAME";

const payload = {
  target_url: targetUrl,
  event: event,
};

axios
  .post("https://api.woodpecker.co/rest/v1/webhooks/subscribe", payload, {
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
    },
  })
  .then((response) => {
    console.log("Response status:", response.status);
    console.log("Response data:", response.data);
  })
  .catch((error) => {
    console.error("Error:", error);
  });

Response

Response examples

201

Successfully subscribed

{
  "target_url": "https://receiving-url.com/unique_target_url",
  "event": "EVENT_NAME",
  "message": "Subscribed."
}

Body schema

Field	Data Type	Description
target_url	string	The URL where webhook events will be delivered
event	string	The name of the event for which the subscription was created
message	string	A confirmation message indicating the subscription status

400

Invalid request or malformed request syntax. Please review the request body

{
  "status": {
    "status": "ERROR",
    "code": "E_WRONG_PARAM",
    "msg": "Invalid target_url." | "Provided event is incorrect."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

401

An issue with authorization. Please review the authorization guide

{
  "status": {
    "status": "ERROR",
    "code": "E_SESSION",
    "msg": "The API key you've entered is incorrect or no longer valid. Check if you pasted the key correctly. You can generate a new key in Woodpecker: Settings -> API Keys."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

404

Please review the request URL

{
  "status": {
    "status": "ERROR",
    "code": "E_URL_NOT_FOUND",
    "msg": "URL not found: /Woodpecker/rest/v1/campaign_list/someMadeUpURL"
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

409

Conflict. Either you are already subscribed for a given URL - event pair, or you have reached the event subscription limit

{
  "status": {
    "status": "ERROR",
    "code": "E_WRONG_PARAM",
    "msg": "Event defined for this url." | "You can only subscribe to the same webhook 3 times per one account."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message

500

An unknown error. Please try again later.

{
  "status": {
    "status": "ERROR",
    "code": "E_UNNOWN",
    "msg": "Unknown error."
  }
}

Body schema

Field	Data Type	Description
status	object	Contains error details
└─status	string	Overall status, set to ERROR for non-2xx responses
└─code	string	Code indicating the error category
└─msg	string	Descriptive error message