Subscribe to a Slack webhook
Receive Woodpecker notifications about events in your account directly in a Slack channel. First, create a Slack incoming webhook for your chosen channel, then use its URL to subscribe to the events you want to receive.
Request
Endpoint
POST https://api.woodpecker.co/rest/v1/slack_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
Each account can register up to five distinct Slack webhook URLs per event. Custom webhook subscriptions are counted separately.
{
"target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"event": "prospect_replied"
}
Body schema
| Field | Type | Required | Description |
|---|---|---|---|
target_url | string | Yes | Slack incoming webhook URL obtained from your Slack app |
event | string | Yes | One of the supported events |
Request samples
Subscribe to prospect replies
- cURL
- Python
- Java
- Node.js
- PHP
curl --request POST \
--url "https://api.woodpecker.co/rest/v1/slack_webhooks/subscribe" \
--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"
}'
import requests
def subscribe_webhook():
url = "https://api.woodpecker.co/rest/v1/slack_webhooks/subscribe"
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"
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 201:
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)
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/subscribe";
String jsonData = """
{
"target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"event": "prospect_replied"
}
""";
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() == 201) {
System.out.println("POST response: " + response.body());
} 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 subscribeWebhook() {
const url = 'https://api.woodpecker.co/rest/v1/slack_webhooks/subscribe';
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"
};
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
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/subscribe', [
'json' => [
'target_url' => 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX',
'event' => 'prospect_replied',
],
]);
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
- 400
- 401
- 404
- 409
- 500
The subscription was created.
{
"target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"event": "prospect_replied",
"message": "Subscribed."
}
Body schema
| Field | Type | Description |
|---|---|---|
target_url | string | Slack incoming webhook URL as sent in the request |
event | string | Event name as sent in the request |
message | string | Confirmation message, Subscribed. |
Check that the request body is a JSON object, target_url is a valid Slack incoming webhook URL, and event is a supported event name.
{
"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 |
The subscription already exists, the account reached its per-event limit, or too many requests are running concurrently.
{
"status": {
"status": "ERROR",
"code": "E_WRONG_PARAM",
"msg": "Event defined for this url."
}
}
Body schema
| Field | Type | Description |
|---|---|---|
status | object | Contains error details |
└─status | string | Overall status, set to ERROR |
└─code | string |
|
└─msg | string | Error description |
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 |