Send events to Webhooks
HMAC-signed JSON POSTs with retries, replay, and a per-attempt audit trail.
What is Webhooks?
A webhook is an HTTP endpoint owned by your customer that receives a JSON payload every time a relevant event happens in your product. It is the simplest, most universal destination type and the first integration most SaaS customers ask for. Pushrail's webhook adapter sends each event as a POST request with a signed header, retries transient failures, and exposes a full delivery log.
Why deliver events to Webhooks
- Universal, every language and framework has an HTTP server ready to receive a POST.
- Realtime, events arrive within a second of the originating action, not hours later on a schedule.
- Self-serve, customers can register their own endpoint URL inside your dashboard without engineering involvement on your end.
- Composable, webhooks feed into whatever the customer wants to do next: a queue, a Lambda, a workflow tool, or a custom handler.
How Pushrail delivers events to Webhooks
Pushrail sends one HTTP POST per event to the URL the customer configured. Each request carries an HMAC-SHA256 signature in the X-Pushrail-Signature header, a timestamp in X-Pushrail-Timestamp, and the canonical event JSON as the body. Pushrail acknowledges acceptance of the originating event in under 100 milliseconds; the actual delivery happens off the hot path. Non-2xx responses are classified as transient (5xx, timeouts, connection errors) or permanent (4xx other than 408/429), and only transient failures are retried.
Auth and credentials
Each webhook destination has its own signing secret, generated when the destination is created and stored encrypted at rest with AES-256. The customer sees the secret once at creation time and can rotate it from the dashboard; old secrets continue to sign in-flight deliveries until they drain, then are revoked. Customers verify each request by recomputing the HMAC over the timestamp and body and comparing in constant time.
Batching, retries, and replay
Webhooks are delivered one event per request, no batching, so signature verification stays trivial. Transient failures are retried with exponential backoff and jitter; once a delivery exhausts its retries it lands in the per-destination DLQ. Replay lets your customer (or you) re-run any failed delivery, an entire time window, or the whole DLQ, Pushrail re-sends with the same payload and a fresh signature so the receiver's verification still passes.
Example payload
Pushrail accepts the canonical event shape on POST /v1/events. Below is the ingestion request your service makes.
{
"eventType": "order.completed",
"occurredAt": "2026-05-26T14:21:08.493Z",
"source": "billing-service",
"customerExternalId": "acct_8K2zRq",
"idempotencyKey": "order_38a91f-completed",
"correlationId": "req_4f30b2",
"payload": {
"orderId": "ord_38a91f",
"amount": 12900,
"currency": "USD",
"items": [
{ "sku": "PR-PRO-MONTHLY", "qty": 1, "price": 12900 }
]
},
"metadata": {
"tier": "pro",
"region": "us-east-1"
}
}Example configuration
The fields your customer fills in to point Pushrail at their Webhooks setup.
{
"type": "WEBHOOK",
"name": "Production webhook",
"url": "https://api.acme.example/pushrail/events",
"timeoutMs": 10000,
"retryPolicy": "exponential_backoff",
"headers": {
"X-Acme-Source": "pushrail"
}
}Common use cases
- Notify a customer's webhook server when an order completes, a subscription renews, or a workflow finishes.
- Fan events out to a customer's internal automation tool (Zapier, n8n, Make, custom).
- Trigger downstream business logic in a customer's own services without exposing your event bus.
- Power partner integrations where a partner registers their own URL to receive events on the customer's behalf.
Related destinations
Deliver events as NDJSON files into a customer-owned S3 bucket, batched, partitioned, and idempotent.
At-least-once delivery into a customer-owned SQS queue, standard or FIFO, native AWS SDK.
Native Kafka producer with SASL/TLS, deliver events into a customer's topic with configurable partitioning.
Forward product events into a customer's PostHog project, distinct_id mapping, person properties, native API.
Frequently asked questions
Do I have to build my own webhook delivery system?
No. Pushrail's webhook adapter handles HMAC signing, retries, dead-letter queuing, and the delivery log for you. Your service sends one canonical event to Pushrail's ingest API and Pushrail delivers the POST.
How are webhook requests signed?
Each request carries an HMAC-SHA256 signature in the X-Pushrail-Signature header plus a timestamp header. Every destination has its own signing secret, stored encrypted at rest; the customer verifies by recomputing the HMAC over the timestamp and body in constant time.
What happens when a customer's endpoint is down?
Transient failures (5xx, timeouts, connection errors) retry with exponential backoff and jitter, then land in the per-destination dead-letter queue once they exhaust their retries. Permanent 4xx responses are not retried. The customer can replay any failed delivery, a time window, or the whole DLQ once their endpoint is back.
Can customers register and rotate their own webhook secret?
Yes. Customers register their endpoint URL from the dashboard or embedded portal and can rotate the signing secret themselves; old secrets keep signing in-flight deliveries until they drain, then are revoked.