Skip to content

Verifying Webhook Signatures

Every signed delivery lets the receiver prove it came from Sparrow and wasn’t replayed or modified. This page shows how to verify it in Go, plus a sample helper for other common languages: one file you copy into your project, with no package to install.

Sparrow signs in the Standard Webhooks format. A signed delivery carries three headers:

Header Value
webhook-id msg_<delivery-id>
webhook-timestamp Unix seconds when the delivery was sent
webhook-signature Space-separated signatures, e.g. v1,<base64> v1a,<base64>

The signed message is {webhook-id}.{webhook-timestamp}.{raw body}:

  • v1, is HMAC-SHA256 keyed with the webhook’s webhook_secret. A whsec_… secret (the default) is base64-decoded first; any other secret is used as raw bytes.
  • v1a, is Ed25519, verified with the webhook’s hex signing_public_key, which is present when the webhook uses signature_type: "ed25519". There’s no shared secret, so receivers only ever hold a public key.

Every helper rejects a delivery when:

  • a header is missing;
  • the timestamp is more than 5 minutes off in either direction (replay protection);
  • no signature of the requested scheme matches.

The header can carry several space-separated signatures (v1, for HMAC and, on ed25519 webhooks, v1a,); matching any one of the requested scheme is enough. Sparrow does not dual-sign with an old and a new secret: after a rotation every attempt carries only the new HMAC signature, so there is no overlap window.

Every delivery, signed or not, also carries headers that say what it is, so a receiver can route it without reading the body (a transform can reshape the body and drop the event name):

Header Value
X-Sparrow-Event-Type The event type name, e.g. order.paid
X-Sparrow-Event-Version The event type version the event was accepted under, e.g. 2
X-Sparrow-Subscription-ID The subscription that matched the event
X-Sparrow-Event-ID, X-Sparrow-Delivery-ID, X-Sparrow-Webhook-ID The event, delivery and webhook IDs

They are not signed. Route on them only after the signature check passes. Custom webhook or subscription headers can’t override any X-Sparrow-* header listed here.

Scheme Value the receiver needs Where you get it
HMAC (v1, the default) http_config.webhook_secret, e.g. whsec_7P18Fjmj... The response to POST /v1/consumers/{consumer}/webhooks, only there. Reading the webhook later returns it masked (whsec_••••). Store it in the receiver’s secret store when you register. If it’s lost, rotate it: Rotate secret on the webhook page, or POST /v1/consumers/{consumer}/webhooks/{webhook_id}:rotateSecret, which returns the new secret once. Every attempt after the rotation, retries included, is signed with the new secret only (no overlap window), so update the receiver right away.
Ed25519 (v1a) signing_public_key, 64 hex characters Register with "signature_type": "ed25519". The key is in the registration response and in every later GET /v1/consumers/{consumer}/webhooks/{webhook_id}, since it isn’t secret.
Terminal window
curl -X POST http://localhost:8080/v1/consumers/default/webhooks \
-H 'Content-Type: application/json' \
-d '{"url": "https://receiver.example.com/webhook", "events": ["order.created"], "signature_type": "ed25519"}'
# -> "signing_public_key": "d7eb1373...", "http_config": {"webhook_secret": "whsec_DpO3...", ...}

An Ed25519 webhook still gets a webhook_secret and its deliveries carry both signatures, so a receiver can check either one.

Pick your language: the choice applies to every example on this page.

Terminal window
go get github.com/sarathsp06/sparrow/pkg/signature
import (
"io"
"net/http"
"github.com/sarathsp06/sparrow/pkg/signature"
)
func webhook(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body) // raw bytes
if err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
if err := signature.VerifyHMAC(body, r.Header, webhookSecret); err != nil {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
// Ed25519 instead: signature.VerifyEd25519(body, r.Header, signingPublicKeyHex)
w.WriteHeader(http.StatusOK)
}

Custom clock or tolerance: signature.Verifier{Tolerance: 10 * time.Minute}.VerifyHMAC(...).

To see what real signed requests look like, run:

Terminal window
sparrow listen --event order.created

It registers a temporary webhook, checks each delivery’s signature itself, and prints the headers and raw body (signature: verified (v1, HMAC-SHA256)). Push an event from another terminal with sparrow push order.created -d '{"order_id":"ord_1"}'. The temporary webhook’s secret isn’t shown, so this is for looking, not for testing your own verification.

To test your receiver end to end, register a webhook that points at it, give it the secret from the response, and push an event:

Terminal window
curl -X POST http://localhost:8080/v1/consumers/default/webhooks \
-H 'Content-Type: application/json' \
-d '{"url": "http://host.docker.internal:3000/webhook", "events": ["order.created"]}'
# copy http_config.webhook_secret into your receiver's config, then:
sparrow push order.created -d '{"order_id": "ord_1"}'
sparrow tail deliveries --once

A success row means your receiver accepted it. To check that it also rejects bad requests, replay the delivery with one byte of the body changed, or with a webhook-timestamp more than 5 minutes old: both must get a non-2xx. (Use host.docker.internal when Sparrow runs in Docker and the receiver on your machine, with SPARROW_ALLOW_PRIVATE_NETWORKS=true on the server.)

Each helper also takes an optional clock and tolerance (now / nowSeconds / verify_hmac_at / signature.Verifier), so you can unit-test your handler with a fixed recorded request instead of a live one.

Once your receiver is registered, send it a test event from the webhook page or the consumer portal (Test tab), or with the API:

Terminal window
curl -X POST http://localhost:8080/v1/consumers/default/subscriptions/<subscription-id>:sendTestEvent \
-H 'Content-Type: application/json' \
-d '{"event_name": "order.paid"}'

Sparrow sends one delivery of the event type’s sample payload (or of the payload you pass, rendered through the subscription’s transform), signed like a real delivery and marked X-Sparrow-Test: true, and answers with the receiver’s status_code, latency_ms and error_class. It records no delivery and never affects the webhook’s health. Each server allows one test event per webhook every 2 seconds. event_name is the subscription’s event, or any event for a catch-all (*) subscription; an event type that isn’t registered has no sample, so pass a payload for it.