Retry a webhook event
Retry delivery of a single webhook event. Use this endpoint to resend a previously delivered event or retry an event that failed or was skipped during processing.
If the webhook subscription is waiting for an automatic retry due to the target host being unavailable, wait for the retry delay to expire or resume the webhook subscription before retrying a failed or skipped event. Previously delivered events can be resent even while the subscription is delayed.
Request
Endpoint
POST https://api.woodpecker.co/rest/v2/webhooks/events/{id}/retry
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 |
|---|---|---|---|
id | Yes | integer | Event ID from the id field in webhook events |
Request samples
Resend a processed event
- cURL
- Python
- Java
- Node.js
- PHP
curl --request POST \
--url "https://api.woodpecker.co/rest/v2/webhooks/events/12346/retry" \
--header "x-api-key: {YOUR_API_KEY}"
import requests
def retry_webhook_event(event_id):
url = f"https://api.woodpecker.co/rest/v2/webhooks/events/{event_id}/retry"
headers = {"x-api-key": "{YOUR_API_KEY}"}
response = requests.post(url, headers=headers)
if response.status_code == 202:
return "Webhook event queued for retry."
if response.status_code == 204:
return "Webhook event resent."
raise Exception(f"POST request failed: {response.status_code}, {response.text}")
if __name__ == "__main__":
try:
print(retry_webhook_event(12346))
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) {
long eventId = 12346;
String url = "https://api.woodpecker.co/rest/v2/webhooks/events/" + eventId + "/retry";
try {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("x-api-key", "{YOUR_API_KEY}")
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() == 202) {
System.out.println("Webhook event queued for retry.");
} else if (response.statusCode() == 204) {
System.out.println("Webhook event resent.");
} else {
throw new IllegalStateException("POST request failed: " + response.statusCode() + ", " + response.body());
}
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
}
const axios = require('axios');
async function retryWebhookEvent(eventId) {
const url = `https://api.woodpecker.co/rest/v2/webhooks/events/${eventId}/retry`;
const headers = { 'x-api-key': '{YOUR_API_KEY}' };
try {
const response = await axios.post(url, null, { headers });
console.log(response.status === 202 ? 'Webhook event queued for retry.' : 'Webhook event resent.');
} catch (error) {
console.error('POST request failed:', error.response ? error.response.status : error.message);
}
}
retryWebhookEvent(12346);
<?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 {
$eventId = 12346;
$response = $client->post("webhooks/events/{$eventId}/retry");
echo $response->getStatusCode(), "\n";
} catch (RequestException $e) {
echo "Error: ", $e->getMessage(), "\n";
if ($e->hasResponse()) {
echo $e->getResponse()->getBody(), "\n";
}
}
Response
Response examples
- 202
- 204
- 400
- 401
- 404
- 422
- 429
- 500
The failed or skipped event was queued for another processing attempt. Use Get webhook events to check its status.
Body: none
Woodpecker rebuilt the payload and resent the previously processed event. The event keeps its existing status in the history.
Body: none
The request is invalid, or the event cannot be resent. Check the error code for details.
{
"type": "validation_error",
"code": "automatic_retry_scheduled",
"message": "The event will be retried automatically after 2026-10-28T11:11:05Z.",
"request_id": "ec9d565c-e89b-4d88-9fb4-41ea82203315"
}
Body schema
| Field | Type | Description |
|---|---|---|
type | string | Error type: validation_error |
code | string | Error code and next step
|
message | string | Human-readable error summary |
request_id | string/null | Request identifier, or null when unavailable |
The API key is missing or invalid. Review the authentication guide.
{
"title": "Unauthorized",
"status": 401,
"detail": "Invalid api key",
"timestamp": "2026-10-28 11:15:00"
}
Body schema
| Field | Type | Description |
|---|---|---|
title | string | A short title describing the error |
status | integer | The HTTP status code |
detail | string | A detailed message explaining the error |
timestamp | string | The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC |
The event or its subscription could not be found for the authenticated account.
{
"type": "validation_error",
"code": "event_not_found",
"message": "Webhook event not found.",
"request_id": "76a8d41e-80fb-4e63-8796-fbf1e9cb3902"
}
Body schema
| Field | Type | Description |
|---|---|---|
type | string | Error type: validation_error |
code | string | Error code: event_not_found |
message | string | Human-readable error summary |
request_id | string/null | Request identifier, or null when unavailable |
The event could not be resent because target host was unreachable or the payload could not be rebuilt.
- delivery failure message:
The webhook cannot be retried: delivery failed. - payload rebuilding failure:
The webhook cannot be retried: payload rebuilding failed.
{
"type": "validation_error",
"code": "webhook_retry_failed",
"message": "The webhook cannot be retried: delivery failed.",
"request_id": "efaf8aaa-b751-4de1-9212-e69faa1769e2"
}
Body schema
| Field | Type | Description |
|---|---|---|
type | string | Error type: validation_error |
code | string | Error code: webhook_retry_failed |
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.
{
"title": "Too Many Requests",
"status": 429,
"detail": "Too many requests.",
"timestamp": "2026-10-28 11:15:00"
}
Body schema
| Field | Type | Description |
|---|---|---|
title | string | A short title describing the error |
status | integer | The HTTP status code |
detail | string | A detailed message explaining the error |
timestamp | string | The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC |
An unexpected error occurred. Retry the request later. If the error persists, share the request_id with Woodpecker Support.
The response body may be empty.
{
"type": "internal_error",
"code": "internal_server_error",
"message": "An unexpected error occurred on the server.",
"request_id": "4a0edd4d-5354-4070-a25f-2caf942db38b"
}
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 |