Outbound webhooks guide

Outbound webhooks let FastStaq notify external systems when events happen in your app. They are delivered reliably, signed for authenticity, and guarded against SSRF.

Registering an endpoint

1. Open the webhooks section in the dashboard.
2. Add an endpoint URL and select the events you want to receive.
3. Save. FastStaq validates the URL before accepting it.

Verifying signatures

Each delivery is signed with an HMAC signature so you can confirm it really came from FastStaq:

1. Read the signature header on the incoming request.
2. Compute the HMAC of the raw request body using your endpoint's signing secret.
3. Compare in constant time and reject if it does not match.

Always verify the signature before acting on a webhook.

Reliability

• Retries: failed deliveries are retried with backoff.
• Delivery log: every attempt is recorded so you can see status, response codes, and timing.
• Replay: you can re-send an event from the delivery log if your endpoint was down.

SSRF protection

Customer-supplied URLs are checked at both registration and delivery time. FastStaq DNS-resolves the host and rejects private, loopback, link-local, and cloud-metadata addresses (IPv4 and IPv6), defending against DNS rebinding.

For local development only, you may set WEBHOOK_ALLOW_PRIVATE_NETWORKS=true to deliver to 127.0.0.1. It must stay false in staging and production; the server warns at startup if it is enabled.

Best practices

• Respond quickly (a 2xx) and process asynchronously.
• Make handlers idempotent; the same event may arrive more than once.
• Rotate the signing secret periodically.

Related articles

• API keys guide
• Background jobs and observability

Still need help?

Open a support ticket with the endpoint and a sample delivery ID.