Quickstart
You’ll register an event type, point a webhook at a URL you can watch, push one
event, and confirm it was delivered. Every step is a curl command and shows
the response you should get back.
Before you start
Section titled “Before you start”- Sparrow is running on
http://localhost:8080. The quickest way is the Docker Compose file:docker compose up -d. If port 8080 is taken, runSPARROW_PORT=8090 docker compose up -dand use that port in the commands below. - No API key needed. The local Compose file runs with an open API. If you
started the server with
SPARROW_API_KEY, add-H "X-API-Key: <your key>"to every command below; without it you get401. jqis optional. The responses below are pretty-printed; add| jqto get the same.
All URLs use the default consumer. A consumer is a namespace for webhooks and
events, usually one per customer; any name works.
-
Register an event type
Sparrow only accepts events whose type is registered, so define
order.createdfirst:In the UI: Events, then Register Event. Enter the name and description and click Register Event.
Terminal window curl -X POST http://localhost:8080/v1/event-types \-H "Content-Type: application/json" \-d '{"name": "order.created", "description": "Fires when a new order is placed"}'You get the event type back, active and at version 1:
{"name": "order.created","description": "Fires when a new order is placed","active": true,"version": 1,"created_at": "2026-10-08T14:12:44.679012Z","updated_at": "2026-10-08T14:12:44.679012Z"} -
Get a URL you can watch
Open Testhooks in a browser, click Create endpoint and copy its URL (it looks like
https://testhooks.vercel.app/h/a1b2c3d4). Every request sent there shows up on that page, headers and body included, and Testhooks can check Sparrow’s signatures for you.Testhooks is what we use to test and watch Sparrow’s deliveries. It is open source (GitHub), built by Sparrow’s author, and you can self-host it.
-
Register a webhook
Replace the URL with yours. Listing
eventsalso creates a subscription to each one, so this single call is all the setup the webhook needs:In the UI: Webhooks, then Register Webhook. Paste the URL, pick
order.createdunder events and click Register webhook. The next screen shows the signing secret once; copy it there.Terminal window curl -X POST http://localhost:8080/v1/consumers/default/webhooks \-H "Content-Type: application/json" \-d '{"url": "https://testhooks.vercel.app/h/your-endpoint-id","events": ["order.created"]}'The response (trimmed):
{"webhook_id": "431b2e95-ac8a-4127-b3f5-601a0110afae","consumer": "default","events": ["order.created"],"url": "https://testhooks.vercel.app/h/your-endpoint-id","active": true,"health": "unknown","signature_type": "hmac","http_config": {"max_retries": 13,"webhook_secret": "whsec_7P18FjmjRrTO9n2JcFKsyHAIItGvgqY4",...}}Save two values:
webhook_id, to look up deliveries in step 6.http_config.webhook_secret, which the receiver uses to verify signatures. It’s shown only in this response. Reading the webhook later returns it masked (whsec_••••); if you lose it, rotate it from the webhook page.
-
Push an event
In the UI: Events, then Push Test Event. Pick
order.created, paste the payload below and click Push Event.Terminal window curl -X POST "http://localhost:8080/v1/consumers/default/events?event=order.created" \-H "Content-Type: application/json" \-d '{"payload": {"order_id": "ord_123","customer": "alice@example.com","total": 49.99}}'Sparrow accepts the event and returns at once (
201). Delivery happens in the background:{"event_id": "9fab6d74-baa0-45cd-af80-7a63ccdc08a5","duplicate": false,"schema_valid": true} -
See it arrive
Within a second or two, a
POSTappears on your Testhooks page. The body is the event envelope, with your payload inside:{"version": "1","event_id": "9fab6d74-baa0-45cd-af80-7a63ccdc08a5","event_name": "order.created","timestamp": "2026-10-08T14:13:05Z","attempt": 1,"payload": {"customer": "alice@example.com","order_id": "ord_123","total": 49.99}}Among the headers are
webhook-id,webhook-timestampandwebhook-signature(the Standard Webhooks signature, made with yourwebhook_secret), andx-sparrow-event-id,x-sparrow-webhook-id,x-sparrow-delivery-id. -
Check the delivery
In the UI: open the webhook from Webhooks, or go to Deliveries. Click a delivery to see each attempt with its request, response code and timing.
Terminal window curl "http://localhost:8080/v1/consumers/default/deliveries?webhook_id=YOUR_WEBHOOK_ID&limit=10"One delivery, delivered on the first attempt:
{"items": [{"delivery_id": "5fcf5267-6288-443e-b8b9-691037818c80","webhook_id": "431b2e95-ac8a-4127-b3f5-601a0110afae","event_id": "9fab6d74-baa0-45cd-af80-7a63ccdc08a5","event_name": "order.created","status": "success","attempt_count": 1,"max_attempts": 4,"response_code": 200,"error_category": "success"}],"pagination": {"limit": 10, "has_more": false}}Delivery and event lists are newest first and have no total. When
has_moreis true, passpagination.next_cursorback ascursorto get the next, older page.max_attemptsis 4: the first try plus the webhook’s 3 retries.
If you see something else
Section titled “If you see something else”| You see | What it means | What to do |
|---|---|---|
404 with event type "order.created" is not registered when pushing |
The event type doesn’t exist (step 1 was skipped, or the name differs). | Register it, then push again. |
401 Unauthorized on any call |
The server was started with SPARROW_API_KEY. |
Add -H "X-API-Key: <your key>". |
400 with ... addresses are not allowed when registering |
The URL points at localhost or a private network, which Sparrow blocks by default. |
Use a public URL, or start the server with SPARROW_ALLOW_PRIVATE_NETWORKS=true (the local Compose file already does). From inside Docker, reach your machine as host.docker.internal, not localhost. |
"status": "failed" with "error_category": "dns_error" |
The webhook’s host name doesn’t resolve. Sparrow doesn’t retry this. | Fix the URL (PATCH the webhook), then retry with POST /v1/consumers/default/deliveries/{delivery_id}:retry. |
"status": "retrying" with connection_refused, timeout or a 5xx response_code |
The receiver is down or erroring. Sparrow tries again with backoff (retry_backoff_seconds, 60 by default) up to max_retries times; the defaults keep trying for about three days (schedule). |
Bring the receiver back; the next attempt goes through on its own. |
"status": "paused", Held: webhook is paused |
The webhook is paused (you set "active": false, or Sparrow auto-disabled it after repeated failures). Paused deliveries are held, not dropped. |
Resume it with POST /v1/consumers/default/webhooks/{webhook_id}:resume, then retry the held deliveries. See Pausing subscriptions. |
| No deliveries at all | No active subscription matches the event: a different consumer, a different event name, or a label filter that doesn’t match. | Compare the consumer in both URLs and the webhook’s events. |
Error classification lists every
error_category and whether Sparrow retries it.
What happened
Section titled “What happened”- Sparrow stored the event and queued it.
- A fan-out worker found the subscription created in step 3 and created one delivery for it.
- A delivery worker signed the envelope with the webhook’s secret and sent it
as a
POST. - The response code and timing were recorded on the delivery. A failure would have been retried with backoff.
Next steps
Section titled “Next steps”- How it works: events, subscriptions and deliveries in more detail
- Verify webhook signatures on the receiving side
- Payload transformation: send a different body, such as a Slack message
- Recipes: ready-made Slack, PagerDuty, email and other destinations