Testing & Debugging Webhooks

Fire a test payload, inspect the delivery log, and manually retry failed deliveries without waiting for the production trigger.

You don't need to wait for a real subscription to exercise a webhook endpoint. Subscriby has three tools for development and on-call.

Fire a synthetic delivery

From the dashboard: Settings → Webhooks → [endpoint menu] → Send test delivery. From the API:

curl -X POST https://api.subscriby.net/v1/webhook-endpoints/$ID/test \
  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

The test delivery:

Creates a pending delivery row typed as subscription.created.
Signs the payload with the current secret.
Routes it through the same queue that real deliveries use.
Returns the new delivery_id so you can watch its progress.

The data block is a marker, not a realistic event body:

{
  "id": "evt_01HXDELIVERY000000000TST",
  "type": "subscription.created",
  "created_at": "2026-05-18T10:05:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "synthetic": true,
    "endpoint_id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9"
  }
}

Use it to verify DNS, TLS and HMAC verification end-to-end. It will not exercise your field-mapping logic, and because it is always typed subscription.created, it never exercises the subscription.activated path that real paid checkouts take. Branch on data.synthetic to skip business logic on test deliveries.

The test endpoint is rate-limited to 5/min per endpoint (the bucket is keyed by endpoint id, not by the token firing it) — enough for development cadence, low enough that an accidental loop can't flood your target.

Only the member who registered the endpoint, or the team owner, can fire a test (or rotate, pause and delete it). Other team members see the endpoint but the menu actions answer with a refusal; over the API the same call returns 403 FORBIDDEN.

Inspect the delivery log

Every delivery (real or synthetic) shows up in Settings → Webhook Deliveries with:

Endpoint name
Event name
Status (pending / delivered / failed / dead)
HTTP status returned by your handler
Number of attempts so far
Created-at timestamp

Filter by status via the tab bar at the top. Use "Dead-lettered" to find rows that have exhausted retries. Details on a row opens a flyout with the full envelope that was posted, the response body excerpt (first 4KB) your handler returned, and the time of the next attempt.

Use webhook.site for a quick inspection

When you need to see exactly what we POST, the canonical move is:

Visit webhook.site and copy the unique inbox URL.
Register a Subscriby webhook endpoint pointing at it with whatever events you want to see.
Trigger the flow (or fire a test delivery — see above).
webhook.site shows the raw headers, body, and your response.

Tear down the inbox when you're done so test deliveries don't keep flowing.

Manually retry a failed or dead row

From the dashboard: Settings → Webhook Deliveries → [row menu] → Retry delivery. Retry resets status to pending and attempts to 0, clears the recorded response, and queues the worker again immediately. Retrying is dashboard-only — there is no /v1/webhook-deliveries REST surface.

Common failure modes

Symptom	Likely cause
`HTTP 401` or `403` from your handler	Signature verification rejecting payload — check you're using the latest secret and the raw body (not JSON-reparsed).
`Connection refused`	Target service down, or behind a firewall the webhook worker can't reach.
`SSL handshake failed`	Expired certificate or a custom CA. Subscriby validates the full chain.
`DNS resolution failed`	The hostname stopped resolving after registration; fix the record or register the new URL.
Delivery succeeds but downstream never fires	Your handler returned 200 but crashed before enqueuing the work. Queue it first, then respond.