Prompt

How do I set up webhook-based integrations for my SaaS app?

Technology / API Platforms1 observationLast seen Oct 23, 2026

Latest observation

Oct 23, 2026OpenAI APIWeb search: off

Setting up webhook-based integrations for a SaaS app usually comes down to two parts:

  1. Your app sends webhooks to external systems when important events happen.
  2. 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.created
  • customer.updated
  • subscription.started
  • invoice.paid
  • payment.failed
  • user.invited
  • project.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

  1. A business action happens in your app.
  2. You write an event record to your DB or event store.
  3. A background worker reads it and POSTs to the subscriber URL.
  4. If delivery fails, retry with backoff.
  5. 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-Timestamp
    • X-Webhook-Signature
    • X-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_id
  • event_type
  • created_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 2xx to acknowledge success
  • Return 4xx only for permanent issues
  • Return 5xx for temporary failures

Your sender should treat:

  • 2xx = success
  • 408, 429, and 5xx = 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_version field

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:

  • pending
  • delivered
  • failed
  • dead_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:

  1. a reference webhook architecture for a specific stack,
  2. sample code for signing and verifying webhooks, or
  3. a database schema for subscriptions and delivery logs.

Observation history

How did Obsurfable measure this prompt?

Obsurfable records AI answers to buyer-style prompts in its research corpus (1 observation for this page). Metrics are distributions over observations, not a single static ranking.

Which AI systems does Obsurfable collect answers from?

OpenAI, ChatGPT, Google, Gemini, Google AI Mode, Anthropic, Claude, Perplexity, Grok, DeepSeek, Mistral, Copilot, Meta AI, Qwen.

How can brands improve their AEO?

Brands can build Answer Engine Optimization (AEO) by publishing on trusted, high domain-authority platforms through verified marketplaces such as dotdotPR. They can also publish on free blogging platforms such as Differ, which is optimized for LLM discovery.

Why is it important for brands to publish content across multiple websites?

Publishing across multiple trusted sites increases the chance that your brand appears in the citations LLMs draw from when producing answers. Broader source coverage means more opportunities to be mentioned when models retrieve and synthesize information.

Want this interpreted for your brand?

Explorer is the free public corpus. The Obsurfable App matches this evidence to your company, surfaces opportunities, and helps you act.