Prompt
How do I set up webhook-based integrations for my SaaS app?
Latest observation
Setting up webhook-based integrations for a SaaS app usually comes down to two parts:
- Your app sends webhooks to external systems when important events happen.
- Your app receives webhooks from external systems when they notify you of changes.
Here’s a practical blueprint for both.
1) Decide what events to publish
Start with a clear event list. Good webhook events are:
customer.createdcustomer.updatedsubscription.startedinvoice.paidpayment.faileduser.invitedproject.deleted
Tips:
- Prefer business events over raw database changes.
- Make events stable and versioned.
- Include enough context so the receiver doesn’t need to call you immediately for basic info.
A typical event payload:
{
"id": "evt_12345",
"type": "invoice.paid",
"created_at": "2026-10-23T12:00:00Z",
"data": {
"invoice_id": "inv_987",
"customer_id": "cus_456",
"amount": 4999,
"currency": "USD"
}
}
2) Build webhook delivery infrastructure
Core components
- Event producer: your app emits an event when something happens
- Event queue / job system: stores delivery tasks asynchronously
- Delivery worker: sends HTTP POST requests to subscriber endpoints
- Retry mechanism: handles transient failures
- Delivery log: records success/failure for debugging
Delivery flow
- A business action happens in your app.
- You write an event record to your DB or event store.
- A background worker reads it and POSTs to the subscriber URL.
- If delivery fails, retry with backoff.
- Track attempts and final status.
Important: don’t send webhooks inline in the user request. Use async delivery so your app stays fast and reliable.
3) Let customers subscribe to webhook endpoints
In your SaaS admin/settings, offer something like:
- Webhook URL
- Events to subscribe to
- Secret/signing key
- Status/health
- Retry policy visibility
Example subscription record:
{
"id": "whsub_001",
"tenant_id": "tenant_abc",
"url": "https://example.com/webhooks",
"events": ["invoice.paid", "payment.failed"],
"secret": "whsec_xxx",
"active": true
}
4) Secure webhook delivery
Sign requests
Use an HMAC signature so recipients can verify the request came from you.
Common pattern:
- Compute signature over raw body + timestamp using a shared secret
- Send in headers such as:
X-Webhook-TimestampX-Webhook-SignatureX-Webhook-Id
Example header:
X-Webhook-Signature: t=1729680000,v1=6f2a...c9
Receiver verification
The receiver should:
- Check timestamp to prevent replay attacks
- Recompute the HMAC using the raw request body
- Compare signatures in constant time
Other security practices
- Use HTTPS only
- Support secret rotation
- Allow IP allowlisting if feasible
- Never send sensitive secrets in the payload unless absolutely necessary
5) Make deliveries reliable
Retry policy
For non-2xx responses or timeouts:
- Retry with exponential backoff
- Add jitter
- Stop after a max attempt count
Example:
- 1 min
- 5 min
- 15 min
- 1 hour
- 6 hours
Idempotency
Webhook receivers may see duplicates. Always make events idempotent by including:
event_idevent_typecreated_at
Receiver should store processed event_ids and ignore duplicates.
Timeouts
Use short timeouts, e.g. 3–10 seconds. If the recipient is slow, fail and retry later.
6) Define a clear response contract
Tell customers:
- Return
2xxto acknowledge success - Return
4xxonly for permanent issues - Return
5xxfor temporary failures
Your sender should treat:
2xx= success408,429, and5xx= retryable- other
4xx= usually non-retryable
7) Provide testing tools
Good developer experience matters a lot.
Include:
- Test webhook button in dashboard
- Event replay
- Delivery logs
- Sample payloads
- Local testing docs using tools like ngrok, Cloudflare Tunnel, or localtunnel
A test webhook endpoint can help users validate setup before going live.
8) Consider event versioning
As your payloads evolve, version them:
- In the event type:
invoice.paid.v2 - Or in a separate
api_versionfield
This prevents breaking integrations when you add/remove fields.
9) Track delivery state
Store:
- subscription ID
- event ID
- attempt count
- last response code
- last response body (careful with sensitive data)
- next retry time
- final status
Useful statuses:
pendingdeliveredfaileddead_lettered
10) If you also need to receive third-party webhooks
For incoming webhooks from services like Stripe, GitHub, Slack, etc.:
- Expose a dedicated endpoint like
/webhooks/provider-name - Validate signatures from the provider
- Make processing async
- Acknowledge quickly with
2xx - Handle duplicates and out-of-order events
- Store raw payloads for debugging
A simple architecture
User action
↓
App creates event
↓
Event store / queue
↓
Webhook worker
↓
HTTP POST to customer endpoint
↓
Customer verifies signature and processes
Minimal implementation checklist
- Event model with unique ID
- Subscription management UI/API
- Async delivery worker
- Retry with exponential backoff
- Signature-based request verification
- Delivery logs and replay
- Idempotency support
- Event versioning
- Test webhook functionality
- Docs with sample payloads and verification steps
Example webhook request
POST /webhooks HTTP/1.1
Host: customer-app.com
Content-Type: application/json
X-Webhook-Id: evt_12345
X-Webhook-Timestamp: 1729680000
X-Webhook-Signature: t=1729680000,v1=6f2a...
{
"id": "evt_12345",
"type": "invoice.paid",
"created_at": "2026-10-23T12:00:00Z",
"data": {
"invoice_id": "inv_987",
"customer_id": "cus_456",
"amount": 4999,
"currency": "USD"
}
}
If you want, I can also give you:
- a reference webhook architecture for a specific stack,
- sample code for signing and verifying webhooks, or
- a database schema for subscriptions and delivery logs.