webhook-development

Webhook Development Skill

Step 1 — Receiving Webhooks

Verify the signature first — before any processing:

// HMAC-SHA256 verification (Go)
func verifySignature(body []byte, signatureHeader, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

// HMAC-SHA256 verification (TypeScript)
async function verifySignature(body: string, signature: string, secret: string): Promise<boolean> {
  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
  const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(body))
  const expected = 'sha256=' + Array.from(new Uint8Array(mac)).map(b => b.toString(16).padStart(2, '0')).join('')
  return expected === signature
}

Respond immediately — enqueue for async processing:

POST /webhooks/stripe
  1. Read raw body (before any parsing)
  2. Verify HMAC-SHA256 signature → 401 if invalid
  3. Return HTTP 200 immediately
  4. Enqueue event → message queue (SQS, RabbitMQ, etc.)

Never do database writes or downstream API calls inside the HTTP handler — the sender's retry logic will time out.

Step 2 — Processing Webhooks (Idempotent Consumer)

Worker loop:
  1. Dequeue event
  2. Check idempotency key (event_id) in processed_events table
     → if found: ack and skip
  3. Begin transaction
     4. Process business logic
     5. Insert event_id into processed_events
  6. Commit
  7. Ack message

Idempotency key: use the sender's event ID (e.g., Stripe's evt_xxx, GitHub's X-GitHub-Delivery header). If the sender does not provide one, derive it from a hash of the payload.

Retry with exponential backoff:

Attempt 1: immediate
Attempt 2: +1 second
Attempt 3: +5 seconds
Attempt 4: +30 seconds
Attempt 5: → dead-letter queue