Resume a webhook subscription
Clear the automatic retry delay for a webhook subscription after a failed delivery attempt. This allows Woodpecker to retry failed events and process new events that were queued while the subscription was delayed, without waiting for the scheduled retry
Use get webhook events to find subscriptions waiting for an automatic retry by checking their events' waiting_for_retry status and auto_retry_after timestamp.
Request
Endpoint
POST https://api.woodpecker.co/rest/v2/webhooks/{id}/resume
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 | Subscription ID from the webhook_config_id field in get webhook events |
Request samples
Resume delivery for a delayed subscription
- cURL
- Python
- Java
- Node.js
- PHP
curl --request POST \
--url "https://api.woodpecker.co/rest/v2/webhooks/98764/resume" \
--header "x-api-key: {YOUR_API_KEY}"
import requests
def resume_webhook_subscription(subscription_id):
url = f"https://api.woodpecker.co/rest/v2/webhooks/{subscription_id}/resume"
headers = {"x-api-key": "{YOUR_API_KEY}"}
response = requests.post(url, headers=headers)
if response.status_code == 204:
return "Webhook subscription resumed."
raise Exception(f"POST request failed: {response.status_code}, {response.text}")
if __name__ == "__main__":
try:
print(resume_webhook_subscription(98764))
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 subscriptionId = 98764;
String url = "https://api.woodpecker.co/rest/v2/webhooks/" + subscriptionId + "/resume";
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() == 204) {
System.out.println("Webhook subscription resumed.");
} 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 resumeWebhookSubscription(subscriptionId) {
const url = `https://api.woodpecker.co/rest/v2/webhooks/${subscriptionId}/resume`;
const headers = { 'x-api-key': '{YOUR_API_KEY}' };
try {
await axios.post(url, null, { headers });
console.log('Webhook subscription resumed.');
} catch (error) {
console.error('POST request failed:', error.response ? error.response.status : error.message);
}
}
resumeWebhookSubscription(98764);
<?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 {
$subscriptionId = 98764;
$response = $client->post("webhooks/{$subscriptionId}/resume");
echo $response->getStatusCode(), "\n";
} catch (RequestException $e) {
echo "Error: ", $e->getMessage(), "\n";
if ($e->hasResponse()) {
echo $e->getResponse()->getBody(), "\n";
}
}
Response
Response examples
- 204
- 400
- 401
- 404
- 429
- 500
The retry delay has been cleared. Queued events can now be processed without waiting for the scheduled retry. Use get webhook events to check their status.
Body: none
The request is invalid, or the webhook subscription has no active retry delay. Check the error code for details.
{
"type": "validation_error",
"code": "webhook_not_paused",
"message": "The webhook is not paused.",
"request_id": "9934ac2f-199e-477b-b695-f2581851d21a"
}
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 subscription could not be found for the authenticated account.
{
"type": "validation_error",
"code": "webhook_not_found",
"message": "Webhook not found.",
"request_id": "76a8d41e-80fb-4e63-8796-fbf1e9cb3902"
}
Body schema
| Field | Type | Description |
|---|---|---|
type | string | Error type: validation_error |
code | string | Error code: webhook_not_found |
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 |