{
    "slug": "webhook_vs_queue",
    "term": "Webhooks vs Message Queues",
    "category": "messaging",
    "difficulty": "beginner",
    "short": "Webhooks push events via HTTP to a registered URL (caller waits for response); message queues decouple sender and receiver — queues are more reliable but require consumer infrastructure.",
    "long": "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.",
    "aliases": [],
    "tags": [
        "messaging",
        "webhooks",
        "http",
        "integration"
    ],
    "misconception": "Webhooks are unreliable and should never be used — webhooks are standard for external integrations. For internal services, use queues.",
    "why_it_matters": "Understanding when to use webhooks vs queues prevents over-engineering (adding Kafka for a simple webhook) or under-engineering (using webhooks for high-volume internal events).",
    "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."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "message_broker",
        "at_least_once_delivery",
        "message_idempotency",
        "pub_sub_pattern"
    ],
    "prerequisites": [
        "message_broker"
    ],
    "refs": [
        "https://stripe.com/docs/webhooks"
    ],
    "bad_code": "// Blocking webhook handler — times out on slow processing:\napp()->post('/webhook/stripe', function($request) {\n    sendConfirmationEmail($request->data); // Slow — times out, Stripe retries\n    return response('OK');\n});",
    "good_code": "// Return 200 immediately, process async:\napp()->post('/webhook/stripe', function($request) {\n    // 1. Verify signature:\n    Stripe::constructEvent($request->body, $request->header('Stripe-Signature'), $secret);\n    // 2. Dispatch to queue:\n    Queue::dispatch(new ProcessStripeWebhook($request->data));\n    return response('', 200); // Return fast\n});",
    "quick_fix": "Return 200 immediately from webhook handler. Process payload in a background job. Verify HMAC signature. Make handler idempotent using event ID.",
    "severity": "medium",
    "effort": "low",
    "created": "2026-03-23",
    "updated": "2026-03-23",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/webhook_vs_queue",
        "html_url": "https://codeclaritylab.com/glossary/webhook_vs_queue",
        "json_url": "https://codeclaritylab.com/glossary/webhook_vs_queue.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Webhooks vs Message Queues](https://codeclaritylab.com/glossary/webhook_vs_queue) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/webhook_vs_queue"
            }
        }
    }
}