Unsubscribe from a Slack webhook
Use this endpoint to stop receiving Slack notifications for a specific event and webhook URL.
Unsubscribing discards any notifications still queued for the subscription. If delivery has been interrupted or you expect notifications to be queued, set safe to true. Woodpecker checks the queue and keeps the subscription active if any notifications are pending.
Request
Endpoint
POST https://api.woodpecker.co/rest/v1/slack_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
Specify both target_url and event. The request selects every subscription for that URL that includes the event. Removing a subscription that covers multiple events stops notifications for all of them.
{
"target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"event": "prospect_replied",
"safe": true
}
Body schema
| Field | Type | Required | Description |
|---|---|---|---|
target_url | string | Yes | Slack incoming webhook URL obtained from your Slack app |
event | string | Yes | Supported event, matched case-insensitively |
safe | boolean | No | When true, checks the selected subscriptions for queued events before removing them. Defaults to false |
Request samples
Unsubscribe from prospect replies after checking the queue
- cURL
- Python
- Java
- Node.js
- PHP
curl --request POST \
--include \
--url "https://api.woodpecker.co/rest/v1/slack_webhooks/unsubscribe" \
--header "Content-Type: application/json" \
--header "x-api-key: {YOUR_API_KEY}" \
--data '{
"target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"event": "prospect_replied",
"safe": true
}'
import requests
def unsubscribe_webhook():
url = "https://api.woodpecker.co/rest/v1/slack_webhooks/unsubscribe"
headers = {
"Content-Type": "application/json",
"x-api-key": "{YOUR_API_KEY}"
}
payload = {
"target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"event": "prospect_replied",
"safe": True
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 200:
return "Subscription removed."
if response.status_code == 204:
return "No matching subscription was removed."
raise Exception(f"POST request failed: {response.status_code}, {response.text}")
if __name__ == "__main__":
try:
data = unsubscribe_webhook()
print("POST response:", data)
except Exception as e:
print("Error:", e)
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) {
try {
HttpClient client = HttpClient.newHttpClient();
String url = "https://api.woodpecker.co/rest/v1/slack_webhooks/unsubscribe";
String jsonData = """
{
"target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"event": "prospect_replied",
"safe": true
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("x-api-key", "{YOUR_API_KEY}")
.POST(HttpRequest.BodyPublishers.ofString(jsonData))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() == 200) {
System.out.println("Subscription removed.");
} else if (response.statusCode() == 204) {
System.out.println("No matching subscription was removed.");
} else {
throw new Exception("POST request failed: " + response.statusCode() + ", " + response.body());
}
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
}
const axios = require('axios');
async function unsubscribeWebhook() {
const url = 'https://api.woodpecker.co/rest/v1/slack_webhooks/unsubscribe';
const headers = {
'Content-Type': 'application/json',
'x-api-key': '{YOUR_API_KEY}'
};
const data = {
"target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"event": "prospect_replied",
"safe": true
};
try {
const response = await axios.post(url, data, { headers });
if (response.status === 200) {
console.log('Subscription removed.');
} else if (response.status === 204) {
console.log('No matching subscription was removed.');
} else {
console.error('POST request failed:', response.status, response.data);
}
} catch (error) {
console.error('POST request failed:', error.response ? error.response.status : error.message);
}
}
unsubscribeWebhook();
<?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('slack_webhooks/unsubscribe', [
'json' => [
'target_url' => 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX',
'event' => 'prospect_replied',
'safe' => true,
],
]);
$status = $response->getStatusCode();
if ($status === 200) {
echo "200 Subscription removed.\n";
} elseif ($status === 204) {
echo "204 No matching subscription was removed.\n";
} else {
echo 'POST request failed: ', $status, ', ', $response->getBody(), "\n";
}
} catch (RequestException $e) {
echo "Error: ", $e->getMessage(), "\n";
if ($e->hasResponse()) {
echo $e->getResponse()->getBody(), "\n";
}
}
Response
Response examples
- 200
- 204
- 400
- 401
- 404
- 409
- 422
- 500
The request removed the matching subscriptions.
Body: empty
No subscription matched the request, or the supplied event name was unrecognized or unsupported for Slack.
Body: empty
Check that the request body is a JSON object and includes target_url as a string.
{
"status": {
"status": "ERROR",
"code": "E_WRONG_PARAM",
"msg": "Invalid target_url."
}
}
Body schema
| Field | Type | Description |
|---|---|---|
status | object | Contains error details |
└─status | string | Overall status, set to ERROR |
└─code | string |
|
└─msg | string | Error description |
The API key is missing or invalid. Review the authentication 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 | Type | Description |
|---|---|---|
status | object | Contains error details |
└─status | string | Overall status, set to ERROR |
└─code | string | Error category |
└─msg | string | Error description |
The request URL does not match an endpoint. Check the endpoint path.
{
"status": {
"status": "ERROR",
"code": "E_URL_NOT_FOUND",
"msg": "URL not found: /rest/v1/slack_webhooks/unknown"
}
}
Body schema
| Field | Type | Description |
|---|---|---|
status | object | Contains error details |
└─status | string | Overall status, set to ERROR |
└─code | string | Error category |
└─msg | string | Error description |
Too many concurrent requests. Retry the request later.
{
"status": {
"status": "ERROR",
"code": "E_TOO_MANY_REQUESTS",
"msg": "Too many requests in one time"
}
}
Body schema
| Field | Type | Description |
|---|---|---|
status | object | Contains error details |
└─status | string | Overall status, set to ERROR |
└─code | string | Error category |
└─msg | string | Error description |
With safe: true, queued events prevent removal. The subscription remains active. Retry after the queued events have been processed.
{
"status": {
"status": "ERROR",
"code": "E_INV_STATUS",
"msg": "Webhook cannot be removed while events are queued"
},
"queued_events_count": 12
}
Body schema
| Field | Type | Description |
|---|---|---|
status | object | Contains error details |
└─status | string | Overall status, set to ERROR |
└─code | string | Error category |
└─msg | string | Error description |
queued_events_count | integer | Number of queued events across the selected subscriptions, including other events they cover |
An unexpected server error occurred. The code and message can vary.
{
"status": {
"status": "ERROR",
"code": "E_UNNOWN",
"msg": "Unknown error."
}
}
Body schema
| Field | Type | Description |
|---|---|---|
status | object | Contains error details |
└─status | string | Overall status, set to ERROR |
└─code | string | Error category |
└─msg | string | Error description |