Webhook Design

Also Known As

TL;DR

Explanation

Webhooks push events to consumer endpoints via HTTP POST. Design considerations: Signature verification (HMAC-SHA256 of the payload with a shared secret — prevents forged payloads), idempotency (the same event may be delivered multiple times — consumers must be idempotent), delivery guarantees (retry with exponential backoff on non-2xx responses), timeouts (consumer must respond within 5-30 seconds — queue slow processing), event ordering (not guaranteed — include timestamps and sequence numbers), and dead letter handling (failed deliveries after retries need alerting).

Common Misconception

Why It Matters

Common Mistakes

• Not verifying HMAC signature — any HTTP client can forge webhook payloads.
• Non-idempotent consumers — retries cause duplicate charges, emails, or database records.
• Slow processing in webhook handler — slow handlers cause timeouts and trigger retries.
• No dead letter handling — failed webhooks silently lost means missed events.

Code Examples

// No signature verification, not idempotent:
$payload = file_get_contents('php://input');
$event   = json_decode($payload);
// No verification — anyone can POST fake events!
if ($event->type === 'payment.completed') {
    $this->processPayment($event->data); // Not idempotent — retries = double charge!
}

// Secure webhook handler:
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// Verify HMAC signature:
$expected = 'sha256=' . hash_hmac('sha256', $payload, WEBHOOK_SECRET);
if (!hash_equals($expected, $signature)) {
    http_response_code(401); exit;
}

$event = json_decode($payload);

// Idempotency — skip if already processed:
if ($this->events->isProcessed($event->id)) {
    http_response_code(200); exit; // Acknowledge but skip
}

// Respond 200 immediately, process asynchronously:
http_response_code(200);
ProcessWebhookJob::dispatch($event->id)->afterResponse();
$this->events->markProcessed($event->id);

References

• ↗ https://stripe.com/docs/webhooks/best-practices

Tags

Related Terms