Get webhook events
Retrieve recent webhook events for the authenticated account.
See which events were processed successfully and when, which are queued or waiting for an automatic retry, and which need investigation. Use this history to review webhook activity from the past 30 days. Each entry represents one event for one subscription. For the current subscriptions themselves, see Get webhook subscriptions.
Request
Endpoint
GET https://api.woodpecker.co/rest/v2/webhooks/events
Headers
x-api-key: {YOUR_API_KEY}
For details on how to authenticate your requests, please see the authentication guide.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
event_type | No | string | Lowercase event name, such as prospect_replied. Use a name from available events |
created_from | No | string | Earliest event creation time to include, e.g. 2026-10-28T00:00:00+01:00 |
created_to | No | string | Latest event creation time to include, e.g. 2026-10-29T00:00:00+01:00 |
next_page_cursor | No | string | Cursor returned by the previous page. See pagination |
On the first page, you can combine the filters or omit them all. Send each filter at most once.
Both date filters require a numeric time zone offset (e.g., +00:00 for UTC). When constructing URLs manually, encode the + sign as %2B. Both bounds are inclusive.
Request samples
Get reply events created on or after October 28, 2026
- cURL
- Python
- Java
- Node.js
- PHP
curl --request GET \
--url "https://api.woodpecker.co/rest/v2/webhooks/events?event_type=prospect_replied&created_from=2026-10-28T00%3A00%3A00%2B01%3A00" \
--header "x-api-key: {YOUR_API_KEY}"
import requests
def get_webhook_events():
url = "https://api.woodpecker.co/rest/v2/webhooks/events"
headers = {"x-api-key": "{YOUR_API_KEY}"}
params = {
"event_type": "prospect_replied",
"created_from": "2026-10-28T00:00:00+01:00",
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
return response.json()
raise Exception(f"GET request failed: {response.status_code}, {response.text}")
if __name__ == "__main__":
try:
print("GET response:", get_webhook_events())
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) {
String url = "https://api.woodpecker.co/rest/v2/webhooks/events"
+ "?event_type=prospect_replied&created_from=2026-10-28T00%3A00%3A00%2B01%3A00";
try {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-api-key", "{YOUR_API_KEY}")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
throw new IllegalStateException("GET request failed: " + response.statusCode() + ", " + response.body());
}
System.out.println("GET response: " + response.body());
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
}
const axios = require('axios');
async function getWebhookEvents() {
const url = 'https://api.woodpecker.co/rest/v2/webhooks/events';
const headers = { 'x-api-key': '{YOUR_API_KEY}' };
const params = {
event_type: 'prospect_replied',
created_from: '2026-10-28T00:00:00+01:00',
};
try {
const response = await axios.get(url, { headers, params });
console.log('GET response:', response.data);
} catch (error) {
console.error('GET request failed:', error.response ? error.response.status : error.message);
}
}
getWebhookEvents();
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
$client = new Client([
'base_uri' => 'https://api.woodpecker.co/rest/v2/',
'headers' => [
'x-api-key' => getenv('WOODPECKER_API_KEY'),
],
]);
try {
$response = $client->get('webhooks/events', [
'query' => [
'event_type' => 'prospect_replied',
'created_from' => '2026-10-28T00:00:00+01:00',
],
]);
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
- 200
- 400
- 401
- 429
- 500
If no events match, events is an empty array and next_page_cursor is null.
{
"events": [
{
"id": 12346,
"webhook_config_id": 98765,
"name": "Replies",
"event_type": "prospect_replied",
"target_url": "https://hooks.example.com/replies",
"created_at": "2026-10-28T12:10:00+01:00",
"processing_started_at": "2026-10-28T12:10:04+01:00",
"processing_finished_at": "2026-10-28T12:10:05+01:00",
"auto_retry_after": null,
"status": "processed",
"reason": null
},
{
"id": 12345,
"webhook_config_id": 98764,
"name": "CRM replies",
"event_type": "prospect_replied",
"target_url": "https://crm.example.com/webhooks/replies",
"created_at": "2026-10-28T12:00:00+01:00",
"processing_started_at": null,
"processing_finished_at": null,
"auto_retry_after": "2026-10-28T12:11:05+01:00",
"status": "waiting_for_retry",
"reason": "processing_error"
}
],
"next_page_cursor": "ZXhhbXBsZS1wYWdlLWN1cnNvcg"
}
Body schema
Timestamps use ISO 8601 with a time zone offset.
| Field | Type | Description |
|---|---|---|
events[] | array | Webhook event history entries |
└─ id | integer | Unique event ID. Use it to retry a webhook event |
└─ webhook_config_id | integer | ID shared by events for the same subscription. Use it to resume a webhook subscription |
└─ name | string or null | Current webhook subscription name |
└─ event_type | string | Event name. See available events |
└─ target_url | string | Current URL configured for the webhook |
└─ created_at | string | When the event entered the webhook queue |
└─ processing_started_at | string or null | When the event was picked up for processing |
└─ processing_finished_at | string or null | When the event finished processing |
└─ auto_retry_after | string or null | Earliest time Woodpecker can retry the delivery of the webhook. Populated for the waiting_for_retry status |
└─ status | string | Processing status |
└─ reason | string or null | Reason for the processing status.
|
next_page_cursor | string or null | Cursor to use for the next page. See pagination |
Check fields to find the parameter to correct. For invalid_fields, correct or omit the filter. For invalid_cursor, use the cursor from the previous response or start again without one.
{
"type": "validation_error",
"code": "invalid_fields",
"message": "Invalid field(s).",
"request_id": "487073e6-c933-488a-a86d-c2ba54b6e9f6",
"fields": [
{
"field": "event_type",
"issue": "unsupported_event_type"
}
]
}
Body schema
| Field | Type | Description |
|---|---|---|
type | string | Error type: validation_error |
code | string | Error code: invalid_fields or invalid_cursor |
message | string | Human-readable error summary |
request_id | string/null | Request identifier, or null when unavailable |
fields | array[object] | Invalid query parameters |
└─ field | string | Name of the invalid query parameter |
└─ issue | string | Description of the validation issue |
The API key is missing or invalid. Review the authentication guide.
{
"type": "validation_error",
"code": "unauthorized",
"message": "Invalid api key",
"request_id": "f4591d36-53f6-4eca-9eb2-327a096ac611"
}
Body schema
| Field | Type | Description |
|---|---|---|
type | string | Error type: validation_error |
code | string | Error code: unauthorized |
message | string | Human-readable error summary |
request_id | string/null | Request identifier, or null when unavailable |
The request exceeded the rate limit. Wait before sending another request. See the rate limiting guide.
{
"type": "validation_error",
"code": "too_many_requests",
"message": "Too many requests in short period of time. Please try again later.",
"request_id": "53ab141d-bb96-42fa-89c4-eafd9570ee6c"
}
Body schema
| Field | Type | Description |
|---|---|---|
type | string | Error type: validation_error |
code | string | Error code: too_many_requests |
message | string | Human-readable error summary |
request_id | string/null | Request identifier, or null when unavailable |
An unexpected error occurred. Retry the request later. If the error persists, share the request_id with Woodpecker Support.
{
"type": "internal_error",
"code": "internal_server_error",
"message": "An unexpected error occurred on the server.",
"request_id": "25a08eb0-5ee3-4a28-8198-2e2cdd4403da"
}
Body schema
| Field | Type | Description |
|---|---|---|
type | string | Error type: internal_error |
code | string | Error code: internal_server_error |
message | string | Human-readable error summary |
request_id | string/null | Request identifier, or null when unavailable |
Event statuses
Use status and reason together to decide what to do.
| Status | What it means | What to do |
|---|---|---|
pending | The event is queued for processing | Wait and check again |
waiting_for_retry | The event is waiting for the next automatic delivery attempt | Check that your server is reachable and returns a 2xx response. Wait until auto_retry_after or resume the subscription to lift the delay for all its queued events |
processing | The event is being processed | Wait and check again |
processed | The event was processed successfully | Check the receiving application's logs to confirm receipt. If your integration needs another delivery, retry the event |
skipped | The event was skipped because the data needed to build the payload changed or is no longer available | Check reason and verify that the related prospect, campaign, or other record still exists and has the expected data |
failed | The event could not be processed | Check reason and address the cause before you retry the event. If the cause is unclear, contact support with the event id and reason |
unknown | The event's processing status could not be determined | Check again. If the status persists and the event is missing from your integration, contact support with the event id |
See the webhooks guide for how Woodpecker handles delivery errors.
Pagination
Each page contains up to 100 events, newest first.
- For the first page, omit
next_page_cursorand send any filters you want to apply. - For the next page, send the returned
next_page_cursor. The cursor retains the original filters. Any filters you send with it are ignored. - When the response returns
next_page_cursorasnull, you have reached the last page.
curl --request GET \
--url "https://api.woodpecker.co/rest/v2/webhooks/events?next_page_cursor={NEXT_PAGE_CURSOR}" \
--header "x-api-key: {YOUR_API_KEY}"