Skip to content

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.

  • Sparrow is running on http://localhost:8080. The quickest way is the Docker Compose file: docker compose up -d. If port 8080 is taken, run SPARROW_PORT=8090 docker compose up -d and 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 get 401.
  • jq is optional. The responses below are pretty-printed; add | jq to 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.

  1. Register an event type

    Sparrow only accepts events whose type is registered, so define order.created first:

    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"
    }
  2. 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.

  3. Register a webhook

    Replace the URL with yours. Listing events also 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.created under 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.
  4. 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
    }
  5. See it arrive

    Within a second or two, a POST appears 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-timestamp and webhook-signature (the Standard Webhooks signature, made with your webhook_secret), and x-sparrow-event-id, x-sparrow-webhook-id, x-sparrow-delivery-id.

  6. 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_more is true, pass pagination.next_cursor back as cursor to get the next, older page.

    max_attempts is 4: the first try plus the webhook’s 3 retries.

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.

  1. Sparrow stored the event and queued it.
  2. A fan-out worker found the subscription created in step 3 and created one delivery for it.
  3. A delivery worker signed the envelope with the webhook’s secret and sent it as a POST.
  4. The response code and timing were recorded on the delivery. A failure would have been retried with backoff.