Skip to content
Documentation sections

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
}
FieldNumber of messages over the period
successdelivered successfully
pendingstill pending
sendingstill being sent — a message can be retried several times
failfailed 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:

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.