Webhooks

Also Known As

TL;DR

Explanation

Webhooks enable event-driven integrations: instead of your application polling an API every minute, the service POSTs a JSON payload to your endpoint the moment an event fires (payment.completed, push.received). Implementing a receiver: expose a public HTTPS endpoint, verify the payload signature (HMAC-SHA256 of the body against a shared secret, constant-time comparison with hash_equals()), respond with 200 immediately, and queue actual processing asynchronously to avoid delivery timeouts. Sending webhooks: store endpoint URLs per customer, deliver with retry and exponential backoff, record all delivery attempts, and support manual replay for debugging.

Common Misconception

Why It Matters

Common Mistakes

• Not validating the webhook signature — any HTTP client can send a fake payload to your endpoint.
• Not returning HTTP 200 quickly and processing asynchronously — slow handlers cause the sender to retry, duplicating events.
• Not handling duplicate delivery — webhook senders retry on timeout or non-2xx; your handler must be idempotent.
• Not logging raw payloads — debugging webhook failures requires the original body.

Avoid When

• The consumer cannot guarantee idempotent processing — duplicate deliveries will cause duplicate side effects.
• The payload contains sensitive data sent to an unverified URL — always validate signatures and use HTTPS.
• The receiving server is unreliable — webhooks can be lost; use a message queue for guaranteed delivery.
• You need request-reply semantics — webhooks are fire-and-forget; use polling or SSE for two-way flow.

When To Use

• Notifying external systems of events in real time without them needing to poll.
• Integrating with third-party platforms (Stripe, GitHub, Shopify) that push events on state changes.
• Triggering CI pipelines, cache purges, or downstream workflows in response to your own events.
• Replacing polling in scenarios where events are infrequent and latency matters.

Code Examples

// No signature validation — accepts any POST as legitimate:
app()->post('/webhook', function(Request $req): Response {
    processEvent($req->json()); // No HMAC verification
    return response('ok', 200);
});
// Add: hash_equals(hash_hmac('sha256', $req->rawBody(), $secret), $req->header('X-Signature'))

// Verify Stripe webhook signature
$payload = file_get_contents('php://input');
$sig = $_SERVER['HTTP_STRIPE_SIGNATURE'];
$event = \Stripe\Webhook::constructEvent($payload, $sig, $secret);

References

• ↗ https://hookdeck.com/webhooks/guides/what-are-webhooks

Tags

Related Terms