Webhook deliveries

Read-only access to delivery attempt history for any of your webhook endpoints. Useful for debugging integration issues, reconciling missed events, and audit trails for compliance reviews.

The webhook_delivery object

{
  "object": "webhook_delivery",
  "id": "ckwhd_xxxxxxxxxxxx",
  "endpoint_id": "ckwhe_xxxxxxxxxxxx",
  "event_type": "payout_paid",
  "status": "delivered",
  "attempts": 1,
  "response_status": 200,
  "response_body": "{\"received\":true}",
  "error_message": null,
  "next_attempt_at": null,
  "delivered_at": "2026-05-05T12:34:56Z",
  "created_at": "2026-05-05T12:34:56Z"
}

Status values

Status	Description
`pending`	Queued, awaiting first attempt
`delivered`	Receiver returned 2xx
`failed`	Receiver returned non-2xx OR timed out — will retry
`giving_up`	All retry attempts exhausted (7 by default) — won’t retry again

List deliveries

GET /v1/webhook_deliveries

Query params

Param	Notes
`limit`	1-100, default 50
`starting_after`	Cursor
`endpoint_id`	Filter to one endpoint
`status`	Filter — `pending` \| `delivered` \| `failed` \| `giving_up`
`event_type`	Filter to one event type, e.g. `payout_paid`

Example

# Recent failed deliveries on a specific endpoint
curl "https://api.swappr.me/v1/webhook_deliveries?endpoint_id=ckwhe_xxx&status=failed&limit=20" \
  -H "Authorization: Bearer sk_test_..."

Response

Standard cursor-paginated list:

{
  "object": "list",
  "has_more": true,
  "data": [
    { "object": "webhook_delivery", "id": "...", "status": "failed", ... },
    ...
  ]
}

Common debugging flows

”Why didn’t I get a webhook for payout X?”

List deliveries for that payout’s reference period:

curl "https://api.swappr.me/v1/webhook_deliveries?event_type=payout_paid&limit=50" \
  -H "Authorization: Bearer sk_test_..."

Look for the delivery with data.reference = po_xxx. Check its status and response_status.
If failed or giving_up, the error_message + response_body will tell you why.
Replay manually from the dashboard if needed.

”Receiver is timing out”

Filter to status=failed and look at the error_message field. Common patterns:

Timeout after 10s — your handler is too slow. Acknowledge the webhook fast (within 5 seconds) and process async.
Connection refused / DNS error — your endpoint is down. Re-deploy + replay deliveries.

”Need a missed event for reconciliation”

Webhooks dropped after 7 retries land in giving_up status. The data is still queryable here — pull the body from data.payload (when admin tooling exposes it; the public API doesn’t expose payload to keep response sizes manageable).

For now, missed events are best replayed via the dashboard’s per-delivery Retry button.

Rate limits

This endpoint counts toward the read tier (120/min). Polling for status changes is fine, but use webhooks themselves as the primary signal — this endpoint is for retrospective debugging, not real-time feeds.

Webhook endpoints Reports