Quickstart

This guide walks you through registering a webhook, pushing an event, and verifying delivery — all using curl.

Note

All examples use http://localhost:8080 (REST/HTTP API). Replace with your server URL in production.

Tip

Running from source instead of a pre-built image? See Build from Source for make run / make docker-dev.

Note

The X-API-Key header is only needed when the server was started with SPARROW_API_KEY set — add -H "X-API-Key: <your-key>" if you have one, or omit it on the default local Compose (which runs without a key). All URLs use the default consumer (bootstrapped on startup); swap the default path segment for another consumer to isolate a different tenant’s webhooks and events.

1. Register an event type

   curl -X POST http://localhost:8080/v1/event-types \
     -H "Content-Type: application/json" \
     -H "X-API-Key: sk_live_..." \
     -d '{
       "name": "order.created",
       "description": "Fires when a new order is placed",
       "active": true
     }'

2. Register a webhook

   curl -X POST http://localhost:8080/v1/consumers/default/webhooks \
     -H "Content-Type: application/json" \
     -H "X-API-Key: sk_live_..." \
     -d '{
       "url": "https://testhooks.sarathsadasivan.com/hooks",
       "events": ["order.created"],
       "active": true
     }'

   Save the webhook_id from the response for later use.

3. Push an event

   curl -X POST "http://localhost:8080/v1/consumers/default/events?event=order.created" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: sk_live_..." \
     -d '{
       "payload": {
         "order_id": "ord_123",
         "customer": "alice@example.com",
         "total": 49.99
       },
       "idempotency_key": "idem_ord_123",
       "ttl_seconds": 3600
     }'

4. Check delivery status

   curl "http://localhost:8080/v1/consumers/default/deliveries?webhook_id=YOUR_WEBHOOK_ID&limit=10" \
     -H "X-API-Key: sk_live_..."

What Just Happened?

1. Sparrow stored the event and enqueued it for async processing
2. The event worker found the matching subscription (created automatically when you registered the webhook with events)
3. A delivery job was created and the webhook worker sent an HTTP POST to your URL
4. The delivery status, response code, and response body were recorded

Next Steps

• Learn how events, webhooks, and deliveries fit together
• Configure webhook secrets for HMAC signature verification
• Add payload transforms using Go templates
• Generate a client from the OpenAPI spec — see Client Libraries