Webhooks vs Message Queues
debt(d7/e5/b5/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints field states 'automated: no', and the code_pattern only hints at webhook presence — not whether it's handled synchronously, lacks HMAC validation, or is non-idempotent. These flaws only surface during code review or when a provider retries a timed-out webhook in production.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix requires several coordinated changes: adding a background job processor, wiring an HMAC signature check, and introducing idempotency logic via event ID tracking. This is more than a one-liner but doesn't span the entire codebase.
Closest to 'persistent productivity tax' (b5). The choice applies to web, cli, and queue-worker contexts. Getting it wrong (e.g., synchronous webhook processing or wrong choice of webhooks vs. queues for internal traffic) imposes ongoing operational burden — duplicate events, retry storms — affecting multiple work streams but not rewriting system architecture.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field identifies a nuanced trap: developers either over-engineer (adding Kafka where a webhook suffices) or under-engineer (using webhooks for high-volume internal events). The common_mistakes also highlight synchronous processing leading to retries and duplicates — a well-documented but frequently hit gotcha.
TL;DR
Explanation
Webhook: sender makes HTTP POST to receiver's URL. Synchronous from sender's perspective. Receiver must be online and respond quickly. Retry logic: varies by provider (GitHub retries 3x, Stripe retries over 3 days). Message queue: sender publishes, broker stores, consumer reads when ready. Consumer can be offline. Decoupled. More reliable (broker persists). Choose webhook when: integrating with third-party services (Stripe, GitHub, Twilio). Choose queue when: internal service communication, high volume, consumer reliability matters. Webhook receiver should: respond 200 immediately, process async, verify signature, be idempotent.
Common Misconception
Why It Matters
Common Mistakes
- Processing webhook payload synchronously — causes timeout → provider retries → duplicates.
- Not verifying webhook signature — HMAC validation required.
- Not idempotent webhook handler — duplicate events on retry.
Code Examples
// Blocking webhook handler — times out on slow processing:
app()->post('/webhook/stripe', function($request) {
sendConfirmationEmail($request->data); // Slow — times out, Stripe retries
return response('OK');
});// Return 200 immediately, process async:
app()->post('/webhook/stripe', function($request) {
// 1. Verify signature:
Stripe::constructEvent($request->body, $request->header('Stripe-Signature'), $secret);
// 2. Dispatch to queue:
Queue::dispatch(new ProcessStripeWebhook($request->data));
return response('', 200); // Return fast
});