Detecting and recovering webhook failures
A webhook delivery fails when your endpoint does not accept it, for example because the URL cannot be resolved or the server answers with an error code. Safecube retries a failed delivery several times before marking it as failed. The Webhooks API detects these failures and resends the messages once the endpoint is fixed.
Detect failures with the API
GET /endpoint/{endpoint_id}/stats returns the delivery statistics of an endpoint over the last 28 days at most. The optional since and until query parameters narrow the period.
curl "https://api.sinay.ai/webhook/api/v1/endpoint/{endpoint_id}/stats?since=2024-06-12T12:00:00Z" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Accept: application/json"
{
"success": 0,
"pending": 0,
"sending": 10,
"fail": 32
}
| Field | Number of messages over the period |
|---|---|
success | delivered successfully |
pending | still pending |
sending | still being sent — a message can be retried several times |
fail | failed after being retried several times |
In this example, the endpoint recorded many failures and no success: fix the endpoint, then resend the failed messages.
Recover failures with the API
Two endpoints resend messages to an endpoint over a period, set by since and an optional until:
POST /endpoint/{endpoint_id}/recoverresends every failed message since the given time.POST /endpoint/{endpoint_id}/replay-missingreplays the messages created aftersincethat were never sent to the endpoint; messages already sent are not resent. A successful request returns204 No Content.
curl -X POST "https://api.sinay.ai/webhook/api/v1/endpoint/{endpoint_id}/replay-missing" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"since": "2024-06-12T12:00:00Z",
"until": "2024-06-12T15:00:00Z"
}'
Detect and recover failures in the Svix dashboard
The Svix dashboard shows the same delivery information in a browser. Open it from the Safecube web application — Developers in the sidebar, Webhooks tab, Open Svix dashboard — or from the link returned by GET /dashboard.
- The Endpoints list shows the error rate of each endpoint.
- The Logs and Activity menus show the messages sent and their delivery attempts. A message can be opened to check what was sent and investigate the error.
A webhook message has one of three statuses:
- Succeeded — the endpoint received the webhook without any error code.
- Sending — delivery failed at least once, and Safecube will retry.
- Failed — every delivery attempt failed.
Once the problem is fixed, failed messages can be resent from the dashboard, one by one or as all the missing messages since a given date.