Prompt

I'm building a SaaS platform and need webhook-driven integrations with retries

Technology / API Platforms2 observationsLast seen Oct 27, 2026

Latest observation

Oct 27, 2026OpenAI APIWeb search: off

A solid webhook integration design for a SaaS platform usually needs four things:

  1. Reliable delivery
  2. Idempotency
  3. Retry/backoff
  4. Observability + replay

Here’s a practical pattern you can use.


1) Recommended webhook flow

Outbound event lifecycle

  1. Your app creates an event, e.g. invoice.paid
  2. Save it in an events table/collection
  3. Enqueue a delivery job for each subscribed webhook endpoint
  4. A worker attempts delivery
  5. On success:
    • mark delivery as delivered
  6. On failure:
    • schedule retry with exponential backoff
    • stop after max attempts
  7. Expose delivery logs and manual replay

2) Webhook payload design

Include enough metadata for consumers to safely process duplicates:

{
  "id": "evt_123",
  "type": "invoice.paid",
  "created_at": "2026-10-27T12:00:00Z",
  "data": {
    "invoice_id": "inv_456",
    "amount": 1200,
    "currency": "usd"
  }
}

Important headers

Send something like:

  • Webhook-Id: evt_123
  • Webhook-Type: invoice.paid
  • Webhook-Timestamp: 1730000000
  • Webhook-Signature: t=...,v1=...

3) Security

Sign requests

Use HMAC with a shared secret per tenant/webhook.

Example approach:

  • Signing string: timestamp.body
  • Signature: HMAC_SHA256(secret, signing_string)

Then consumers verify:

  • signature matches
  • timestamp is recent
  • event ID hasn’t been processed before

Why this matters

  • Prevents spoofed requests
  • Helps detect tampering
  • Protects against replay attacks

4) Retry strategy

A good default:

  • Retry on network errors, timeouts, and 5xx
  • Do not retry on most 4xx responses except maybe 429
  • Use exponential backoff with jitter

Example schedule:

  • attempt 1: immediately
  • attempt 2: after 1 minute
  • attempt 3: after 5 minutes
  • attempt 4: after 30 minutes
  • attempt 5: after 2 hours
  • attempt 6: after 12 hours
  • attempt 7: after 24 hours

Retry rules

  • 2xx: success
  • 408, 429, 5xx: retry
  • 400, 401, 403, 404: usually fail permanently
  • timeout / DNS / connection reset: retry

5) Idempotency

Because retries can duplicate deliveries, the consumer must handle duplicates.

Best practice

Consumers should store Webhook-Id and ignore already-processed IDs.

You can also help by:

  • making evt_123 globally unique
  • keeping a delivery log per endpoint
  • offering an idempotency key header

6) Data model

A simple relational model:

webhook_endpoints

  • id
  • tenant_id
  • url
  • secret
  • status
  • created_at

webhook_events

  • id
  • tenant_id
  • type
  • payload
  • created_at

webhook_deliveries

  • id
  • event_id
  • endpoint_id
  • attempt_count
  • status (pending, delivered, failed)
  • next_attempt_at
  • last_response_code
  • last_error
  • delivered_at

7) Worker implementation pattern

Use a job queue like:

  • Sidekiq / Redis
  • Celery / Redis or RabbitMQ
  • BullMQ
  • SQS + worker fleet
  • Kafka if you already run it

Delivery worker steps

  1. Load next due delivery job
  2. Build signed HTTP request
  3. POST to subscriber endpoint
  4. Measure response time
  5. If success:
    • mark delivered
  6. If retryable failure:
    • increment attempt count
    • compute next retry time
  7. If permanent failure:
    • mark failed

8) Timeout and response expectations

Set a short timeout, like:

  • connect timeout: 3–5s
  • total timeout: 10–15s

Consumers should return 2xx quickly and process asynchronously if needed.

Rule of thumb

Don’t let webhook endpoints block for long business logic. Acknowledge fast, process later.


9) Observability

Make webhook delivery debuggable.

Track:

  • delivery attempts
  • latency
  • response code
  • error message
  • last successful delivery
  • retry count
  • per-endpoint success rate

Expose:

  • dashboard
  • logs
  • manual retry button
  • event replay

10) Operational safeguards

Rate limiting

If a consumer is failing repeatedly:

  • back off more aggressively
  • cap concurrent deliveries per endpoint

Dead letter queue

After max retries:

  • move to dead-letter state
  • allow manual replay

Circuit breaker

If endpoint is consistently failing:

  • pause deliveries temporarily
  • notify the customer

11) Example retry policy

A practical policy:

  • Max attempts: 8
  • Backoff: exponential with jitter
  • Retryable status codes: 408, 429, 500–599
  • Hard fail on: 400, 401, 403, 404, 422
  • Max delivery age: 7 days

12) Example signing logic

Pseudo-code:

timestamp = str(int(time.time()))
body = json.dumps(payload)
message = f"{timestamp}.{body}"
signature = hmac_sha256(secret, message)

headers = {
    "Webhook-Id": event_id,
    "Webhook-Timestamp": timestamp,
    "Webhook-Signature": signature,
    "Content-Type": "application/json"
}

13) What I’d recommend for a SaaS MVP

For an MVP, implement:

  • event table
  • endpoint table
  • delivery attempts table
  • signed POST requests
  • retry queue
  • exponential backoff
  • dashboard with logs
  • manual replay

That gets you a very production-usable system without overengineering.


If you want, I can also give you:

  1. a database schema
  2. a retry algorithm
  3. a reference implementation in Node.js, Python, or Go
  4. a full webhook architecture diagram

Observation history

How did Obsurfable measure this prompt?

Obsurfable records AI answers to buyer-style prompts in its research corpus (2 observations 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.