backend-webhooks

Backend Webhooks

Purpose

Securely receive, verify, retry, and deliver webhooks between services with guaranteed delivery and tamper-proof signatures. Webhooks are the standard mechanism for asynchronous service-to-service event notification.

Agent Protocol

Trigger

Exact user phrases: "webhook", "webhook receiver", "webhook delivery", "signature verification", "HMAC", "event delivery", "outgoing webhook", "incoming webhook", "retry webhook", "webhook endpoint".

Input Context

• Direction: receiving incoming webhooks or sending outgoing webhooks.
• Security requirements (signing, IP allowlisting).
• Expected volume and payload size.
• Event types and schemas.

Output Artifact

Webhook handler code or configuration. No file unless requested.

Response Format

Direction: {incoming|outgoing}
Auth: {HMAC|Basic|OAuth|None}
Retry: {strategy}
Delivery Guarantee: {at-least-once|exactly-once}

Completion Criteria

• Signature verification for incoming webhooks.
• Payload signing for outgoing webhooks.
• Retry with exponential backoff for failed deliveries.
• Dead-letter queue for permanently failed deliveries.
• At-least-once delivery guaranteed.
• Idempotency handling for duplicate deliveries.

Max Response Length

4 lines per webhook. 20 lines for full implementation.

Architecture Decision Tree

Should I Use Webhooks or Polling?

Does the consumer need near-real-time notification?
  ├── Yes → Webhooks (push-based, lower latency)
  └── No → Is the consumer behind a firewall?
            ├── Yes → Polling (consumer pulls when ready)
            └── No → Does the consumer need guaranteed delivery?
                      ├── Yes → Webhooks + retry + DLQ
                      └── No → Webhooks (best-effort)

Outgoing vs Incoming Webhook Design

Are you sending events to external systems?
  ├── Yes → Outgoing webhooks:
  │   ├── Subscription management (CRUD endpoints)
  │   ├── Payload signing (HMAC-SHA256)
  │   ├── Retry with backoff (5 attempts)
  │   ├── Dead letter queue (after max retries)
  │   ├── Rate limiting per subscription
  │   └── Consumer-managed endpoint configuration
  └── No → Incoming webhooks:
      ├── Signature verification (timing-safe)
  │   ├── Timestamp validation (tolerance window)
  │   ├── Payload validation (schema check)
  │   ├── Idempotency handling (X-Webhook-ID)
      └── Fast acknowledgment (200 before processing)