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 five 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 samples

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"
  }'

Python

import requests

def subscribe_webhook():
  url = "https://api.woodpecker.co/rest/v1/webhooks/subscribe"
  headers = {
    "Content-Type": "application/json",
    "x-api-key": "{YOUR_API_KEY}"
  }
  payload = {
    "target_url": "https://receiving-url.com/unique_target_url",
    "event": "EVENT_NAME"
  }
  
  response = requests.post(url, headers=headers, json=payload)
  
  if response.status_code == 200:
    return response.json()
  else:
    raise Exception(f"POST request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    data = subscribe_webhook()
    print("POST response:", data)
  except Exception as e:
    print("Error:", e)

Java

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

public class WoodpeckerApiClient {
  private static final String API_KEY = "{YOUR_API_KEY}";
  private static final String URL = "https://api.woodpecker.co/rest/v1/webhooks/subscribe";

  public static void main(String[] args) {
    try {
      HttpClient client = HttpClient.newHttpClient();
      String jsonPayload = "{\"target_url\": \"https://receiving-url.com/unique_target_url\", \"event\": \"EVENT_NAME\"}";
      
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(URL))
        .header("Content-Type", "application/json")
        .header("x-api-key", API_KEY)
        .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
        .build();
      
      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      
      if (response.statusCode() == 201) {
        System.out.println("POST response: " + response.body());
      } else {
        System.err.println("POST request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require('axios');

async function subscribeWebhook() {
  const url = 'https://api.woodpecker.co/rest/v1/webhooks/subscribe';
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': '{YOUR_API_KEY}'
  };
  const data = {
    "target_url": "https://receiving-url.com/unique_target_url",
    "event": "EVENT_NAME"
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log('POST response:', response.data);
  } catch (error) {
    console.error('POST request failed:', error.response ? error.response.status : error.message);
  }
}

subscribeWebhook();

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.woodpecker.co/rest/v1/',
  'headers'  => [
    'x-api-key'     => getenv('WOODPECKER_API_KEY'),
    'Content-Type'  => 'application/json',
  ],
]);

try {
  $response = $client->post('webhooks/subscribe', [
    'json' => [
      'target_url' => 'https://receiving-url.com/unique_target_url',
      'event' => 'EVENT_NAME',
    ],
  ]);
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

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 5 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