Chapter 5: Webhooks: Receiving Events from Slack, Discord, and WebEx

The Webhook Model

A webhook is a "push" delivery mechanism: instead of your gateway holding open a persistent connection and pulling events, the platform issues an ordinary outbound HTTP POST to a public URL you register whenever something happens. This inverts the usual client/server roles for that request — when a message is posted in Slack, Slack's servers become the HTTP client and your endpoint becomes the server.

An analogy: a persistent WebSocket connection is like waiting in line at a bank teller's window. A webhook is like giving the bank your phone number and hanging up — they call you when your transaction clears. This frees you from holding a line open, but it means you must publish a phone number the whole world can dial, and decide on every call whether the caller is really who they claim to be.

Figure 5.3: The webhook push model — the platform becomes the HTTP client.

Because anyone on the internet can POST to your URL, two problems must be solved before any event is trusted: proving the endpoint belongs to you (a one-time handshake) and proving each subsequent request genuinely came from the platform and was not tampered with (per-request signature validation).

Public reachability, tunnels, and cloud endpoints

Because the platform initiates the connection, your endpoint must be reachable from the public internet. In production this is a cloud endpoint with a stable HTTPS URL behind a load balancer with a real TLS certificate. During development your gateway runs on localhost, which the platform's servers cannot reach. The standard fix is a tunnel: a tool such as ngrok opens an outbound connection from your laptop to a public relay and gives you a temporary public HTTPS URL that forwards inbound requests to your local port.

Two practical notes. Webhook URLs must be HTTPS in production; platforms will not deliver over plaintext HTTP. And a free ngrok URL changes every restart, so you must re-register the new URL (and re-run the verification handshake) each session.

At-least-once delivery, retries, and duplicates

Webhook platforms guarantee at-least-once delivery: every event will be delivered at least once, retrying on failure until the receiver acknowledges it. The signal for "success" is your HTTP 2xx response. If the platform does not receive a timely 2xx — because your handler was slow, crashed, or the network hiccuped — it treats the delivery as failed and retries. Slack, for instance, retries a failed event up to three times with backoff (immediately, then after 1 minute, then after 5 minutes). The unavoidable consequence: the same event can arrive more than once, so you engineer processing to tolerate duplicates rather than chasing impossible exactly-once delivery.

Platform Specifics

The three platforms share the same shape — POST an event, expect a fast 2xx — but differ in their handshake and, crucially, in how they prove authenticity. Slack and WebEx use symmetric HMAC; Discord uses asymmetric Ed25519.

Slack: challenge handshake and signing secret

The URL verification challenge is the handshake. When you first configure your Request URL, Slack sends a one-time POST whose JSON type is url_verification, containing token, challenge, and type. Your endpoint must respond within a few seconds with an HTTP 200 that echoes the challenge back. This proves you control the endpoint and happens once per URL registration.

Figure 5.4: Slack URL verification challenge handshake.

The signing secret handles per-request authenticity. Each inbound request carries X-Slack-Request-Timestamp and X-Slack-Signature (of the form v0=<hex_digest>). You reconstruct a base string by concatenating, with literal colons, v0, the timestamp, and the raw, unparsed request body bytes:

import hashlib, hmac, time

def verify_slack(headers, raw_body, signing_secret):
    ts = headers["X-Slack-Request-Timestamp"]
    if abs(time.time() - int(ts)) > 60 * 5:      # 5-minute replay window
        return False
    base = f"v0:{ts}:{raw_body.decode()}"
    digest = "v0=" + hmac.new(
        signing_secret.encode(), base.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(digest, headers["X-Slack-Signature"])

Two details are load-bearing. The HMAC must be computed over the raw bytes exactly as received; if a framework parses and re-serializes the JSON, the recomputed signature will not match. And the timestamp check rejects any request more than five minutes from now, defeating replays. hmac.compare_digest compares in constant time, defeating timing attacks.

WebEx: registration and HMAC-SHA1

Cisco WebEx webhooks are created programmatically via the REST API, specifying a resource (such as messages) and an event (such as created), plus a targetUrl. This resource/event filtering means you subscribe only to what you care about. For authenticity, WebEx signs each webhook with HMAC-SHA1 over the raw payload using a secret you supply at registration, delivered in X-Spark-Signature. The logic mirrors Slack's, but uses SHA-1, has no timestamp in the base string, and a differently named header.

Discord: Ed25519 public-key verification

Where Slack and WebEx use a symmetric secret, Discord uses asymmetric Ed25519 public-key signatures. Discord holds a private key and signs each interaction; you get only the corresponding public key. You verify signatures but can never forge one — a leaked public key does not let an attacker impersonate Discord. Think shared house key (HMAC) versus tamper-evident wax seal (Ed25519).

Each request carries X-Signature-Ed25519 and X-Signature-Timestamp. The signed message is the concatenation timestamp + body:

from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError

PUBLIC_KEY = "your_app_public_key_hex"
verify_key = VerifyKey(bytes.fromhex(PUBLIC_KEY))

def verify_discord(signature, timestamp, raw_body):
    try:
        verify_key.verify(
            f"{timestamp}{raw_body}".encode(),
            bytes.fromhex(signature),
        )
        return True
    except BadSignatureError:
        return False

Discord's handshake is folded into verification: on first saving an Interactions Endpoint URL, Discord sends a PING (type == 1); you must verify the signature and respond 200 with {"type": 1} (a PONG). Critically, Discord also sends deliberately invalid signatures to confirm you reject them with 401 — so a receiver that blindly returns PONG without verifying will fail registration.

Figure 5.1: Per-platform webhook comparison.

Acknowledgement Deadlines

The 3-second rule and fast-ack

Slack's Events API and Discord's interactions both require an HTTP 2xx within roughly 3 seconds; others document 5–30 second windows (GitHub allows about 10). The deadline exists because the platform's HTTP client will not wait forever; past the ceiling it times out, treats the delivery as failed even if you processed it, and retries.

This is why real receivers do only the minimum inline — the fast-ack pattern: (1) read the raw body, (2) verify the signature and timestamp, (3) persist durably or enqueue, and (4) return 200/202 right away. It does not call an LLM, write large records, or hit downstream APIs inline. Returning 202 Accepted is semantically honest: "I have accepted this for processing," not "I have finished." Discord offers an in-band version — a "deferred" response (type 5) that acknowledges now and lets you edit the reply later.

Handing work to a durable queue

The critical word is durable: persisting the event to a durable queue before you ack means that if your worker crashes, the event is still in the queue. Options include Redis Streams, RabbitMQ, AWS SQS, Kafka, Celery/RQ with a broker, or a database "outbox" table.

Figure 5.5: Fast-ack, then enqueue — a fast web tier decoupled from a slow worker tier.

This decoupling is the single most important design decision for a multi-channel gateway. The web tier's only job is to be fast and reliable; the worker tier absorbs latency, spikes, and failures. If a worker crashes mid-task, the queue's own retry and visibility-timeout machinery re-processes the message without the platform ever knowing, and you can scale the slow AI logic separately from the fast HTTP layer.

Idempotency keys and deduplication

At-least-once delivery makes duplicates inevitable. Since exactly-once delivery is unattainable, you engineer idempotent processing: processing the same event twice yields the same result as once. The tool is the idempotency key — a stable identifier constant across retries: Slack's event_id, Discord's interaction ID, Stripe's event.id. Before processing, you atomically check whether you have seen that key (via INSERT ... ON CONFLICT DO NOTHING, Redis SETNX, or a unique constraint). If new, process and record; if a duplicate, skip and still return 2xx so the platform stops retrying.

One constraint is easy to overlook: the dedup store's TTL must outlive the platform's entire retry window. Slack retries over roughly five minutes, but others retry for hours or days; if a dedup entry expires before the last retry, that late retry slips past the empty check and is processed twice.

Building a Robust Receiver

The end-to-end flow is a fixed sequence executed inside the few-second budget: receive POST → capture raw body → verify signature and timestamp (reject if bad) → extract the idempotency key → INSERT it, skipping if present → enqueue → return 202. A per-platform route lets each endpoint pull the right headers and dispatch to the right verifier:

from fastapi import FastAPI, Request, Response, HTTPException

app = FastAPI()

@app.post("/webhooks/slack")
async def slack_webhook(request: Request):
    raw = await request.body()            # RAW bytes, before JSON parsing
    if not verify_slack(request.headers, raw, SLACK_SIGNING_SECRET):
        raise HTTPException(status_code=401)
    payload = await request.json()
    if payload.get("type") == "url_verification":     # one-time handshake
        return {"challenge": payload["challenge"]}
    if already_seen(payload["event_id"]):             # dedup
        return Response(status_code=202)
    await enqueue(payload)                             # durable queue
    return Response(status_code=202)                  # fast-ack

The Discord route follows the same skeleton but verifies with Ed25519 and answers the PING with a PONG:

@app.post("/webhooks/discord")
async def discord_webhook(request: Request):
    raw = await request.body()
    sig = request.headers["X-Signature-Ed25519"]
    ts = request.headers["X-Signature-Timestamp"]
    if not verify_discord(sig, ts, raw.decode()):
        raise HTTPException(status_code=401)          # required by Discord
    payload = await request.json()
    if payload["type"] == 1:                          # PING
        return {"type": 1}                            # PONG
    if already_seen(payload["id"]):
        return Response(status_code=202)
    await enqueue(payload)
    return Response(status_code=202)

The essential structural point: capture await request.body() first, and never verify against await request.json(), because re-parsed JSON breaks the raw-body signature on both platforms.

Verifying signatures per platform

The dispatch table is the heart of the receiver: getting any cell wrong means rejecting genuine traffic or, worse, accepting forged traffic. Each platform contributes its verify_* function, but all three share non-negotiable rules: operate on raw bytes, use constant-time comparison where HMAC is involved, and fail closed — an unverifiable request is rejected, never processed. Also note HTTP header names are case-insensitive; FastAPI's request.headers already handles this, which suits a multi-platform ingress.

Figure 5.6: Per-request signature verification decision flow (fail closed).

Structured logging and observability at ingress

The webhook route is the front door of the gateway, which makes it the best place to observe. Because every event passes through, structured logging at ingress — machine-parseable key/value records — lets you answer operational questions later: which platform, was the signature valid, was it a duplicate, how long did the ack take. At minimum log the platform, the event/idempotency key, the verification outcome, dedup vs fresh enqueue, and the response latency. Crucially, never log the signing secret or raw signatures, and treat message content as sensitive. This visibility turns "duplicates are expected" and "acks must be fast" into things you can measure — for example, alerting when ack latency creeps toward the three-second ceiling.