Unsubscribe from 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.

Use this endpoint to stop receiving notifications for specific events through a webhook.

Request

Endpoint

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

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

{ 
  "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 are currently delivered
event	string	Event you would like to unsubscribe from Available events

Request sample

Subscribe to a webhook

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v1/webhooks/unsubscribe" \
  --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/unsubscribe"))
      .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/unsubscribe", 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

200

Successfully unsubscribed

Status: 200
Body: none

204

Webhook subscription, URL - event pair not found.

Status: 204
Body: none

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/webhooks/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

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