Chapter 4: Networking Fundamentals for Chat Integrations

HTTP for Integrators

HTTP (HyperText Transfer Protocol) is the request/response protocol that every REST-style chat API speaks. A client sends a request; a server returns a response. The details of methods, headers, bodies, and status codes are exactly what separate a fragile integration from a robust one.

The methods you will use most as an integrator map to CRUD operations:

Headers carry the metadata that makes the request work: Content-Type: application/json tells the server how to parse the body, Authorization: Bearer <token> proves who you are, and User-Agent identifies your client. The body — for chat APIs, almost always JSON — carries the actual data.

Status codes are grouped into five classes by their leading digit, and knowing the class tells you how to react:

The distinction between 4xx and 5xx is the single most important operational rule in this chapter. A 400 or 401 means retrying the identical request will fail identically. A 500 or 503 is usually transient. The one 4xx you do retry is 429 Too Many Requests.

Figure 4.3: The HTTP request/response cycle for a gateway outbound call.

An operation is idempotent if performing it many times has the same effect as performing it once. GET and DELETE are naturally idempotent; POST is the dangerous one, because naively retrying a "post message" request can produce two identical messages — the classic double-send bug. Because networks fail ambiguously (a lost response looks identical to a lost request), the industry answer is an idempotency key: a unique client-generated identifier that lets the server recognize a retry and return the original result instead of acting twice.

Chat and messaging APIs protect themselves with rate limits. When you exceed one, the API returns 429 Too Many Requests, typically with a Retry-After header telling you how many seconds to wait. A well-behaved gateway honors it rather than hammering the endpoint.

REST (Representational State Transfer) is the architectural style most chat platform APIs follow: resources live at noun-based URLs (/channels/{id}/messages), the method expresses the action, JSON is the interchange format, and authentication travels in the Authorization header. Slack notably can return 200 OK at the HTTP layer while signaling a logical failure via an "ok": false field — so you must check both the status code and the payload.

TLS, Auth, and Verification

TLS (Transport Layer Security, the "S" in HTTPS) turns a plaintext TCP connection into an encrypted, integrity-protected channel. It does three things: encryption (eavesdroppers see only ciphertext), integrity (tampering is detected), and authentication (the client verifies the server's identity via its certificate).

The setup happens in a TLS handshake performed once when the connection opens. The client and server agree on a cipher, the server presents an X.509 certificate signed by a trusted Certificate Authority, the client validates it, and the two derive a shared session key. The handshake involves multiple round trips and public-key cryptography, making it computationally and latency-expensive — a fact central to connection pooling. Every reused connection saves a full handshake.

For a gateway this means webhook endpoints must be served over HTTPS. But TLS guarantees only that the channel is confidential; it does not prove that whoever POSTed to your public URL is really Slack. Anyone on the internet can open a TLS connection. That gap is what HMAC verification closes.

Figure 4.4: The TLS handshake that opens an encrypted channel.

Two distinct secrets govern trust. A bearer token (Slack's xoxb-...) authenticates outbound calls — the requests you make to the platform, placed in the Authorization: Bearer <token> header. A signing secret authenticates inbound calls — the webhooks the platform sends you. It is never transmitted; instead it is used to compute an HMAC signature over each request.

HMAC (Hash-based Message Authentication Code) combines a hash function — SHA-256 for Slack — with the shared secret. Because both sides hold the secret, both can compute the same HMAC over the same bytes; a third party cannot forge a valid one. Slack's procedure:

1. Capture the raw request body — the exact bytes Slack sent — before any JSON parsing. Re-serializing parsed JSON can reorder keys or change whitespace and silently break verification.
2. Check the timestamp for freshness using X-Slack-Request-Timestamp. Reject anything older than five minutes to defend against replay attacks.
3. Build the signature base string: v0:{timestamp}:{body}.
4. Compute HMAC-SHA256 of that base string using the signing secret as key, hex-encode it, and prefix v0=.
5. Compare securely against X-Slack-Signature with a constant-time comparison — never ==.

import hashlib
import hmac
import time

def verify_slack(signing_secret: str, timestamp: str, body: bytes, sig: str) -> bool:
    # Step 2: reject stale requests to block replay attacks
    if abs(time.time() - int(timestamp)) > 60 * 5:
        return False

    # Step 3: reconstruct the exact base string Slack signed
    base = f"v0:{timestamp}:{body.decode()}".encode()

    # Step 4: recompute the HMAC-SHA256 signature with the shared secret
    computed = "v0=" + hmac.new(
        signing_secret.encode(), base, hashlib.sha256
    ).hexdigest()

    # Step 5: constant-time comparison, NOT ==
    return hmac.compare_digest(computed, sig)

Why constant-time comparison? A naive computed == sig short-circuits at the first differing byte, so its runtime leaks how many leading bytes matched. An attacker measuring response times could recover the correct signature byte by byte — a timing attack. hmac.compare_digest compares in time independent of where the strings differ.

Figure 4.5: HMAC signature verification flow for an inbound webhook.

Figure 4.1: Two secrets, two directions.

Your webhook URL is public by necessity, which means it is also public to attackers. Without signature verification, anyone who discovers the URL can POST forged events. TLS does not help; the attacker simply opens their own valid TLS connection. Signature verification is therefore a mandatory trust boundary: read the raw body first, verify before parsing, return 401/403 on failure, and rotate the signing secret immediately if it leaks.

Async HTTP Clients

A gateway spends most of its life waiting on the network. Because this work is I/O-bound rather than CPU-bound, asyncio is the natural fit: one event loop keeps hundreds of in-flight requests alive, switching to whichever has data ready. Two libraries dominate async HTTP in Python:

The canonical concurrent-fan-out pattern combines a shared client with asyncio.gather:

import asyncio
import httpx

async def fetch(client: httpx.AsyncClient, url: str):
    r = await client.get(url, timeout=10.0)
    r.raise_for_status()
    return r.json()

async def fetch_all(urls: list[str]):
    async with httpx.AsyncClient() as client:
        return await asyncio.gather(*(fetch(client, u) for u in urls))

Recall that opening a new TCP connection — and, over HTTPS, a full TLS handshake — is expensive. A connection pool amortizes that cost by reusing established connections; this reuse is HTTP keep-alive. The single most important rule: instantiate one long-lived client and reuse it everywhere. Creating a new client per request defeats pooling entirely and leaks connections. In httpx, the pool is tuned with httpx.Limits(max_connections=100, max_keepalive_connections=20, keepalive_expiry=5.0). In aiohttp, the same knobs live on the TCPConnector, whose limit_per_host keeps you a polite client to a rate-limited API.

Timeouts are non-negotiable: never issue a network request without one. httpx applies a 5-second default independently to four phases — connect, read, write, and pool. aiohttp uses ClientTimeout with one subtlety: its clock starts the moment session.get() is called, so time spent queued waiting for a free connection counts against the timeout.

Upstreams fail transiently. Retrying blindly and immediately makes things worse: a synchronized retry storm can knock a recovering service back over. The standard remedy is exponential backoff — wait progressively longer (1s, 2s, 4s, 8s) — plus jitter, a small random offset so many clients don't align into synchronized waves. Two rules keep retries safe: only retry retryable errors (429, 500, 502, 503, 504, connection/timeout failures — never a 400 or 401), and pair retries with idempotency.

import asyncio
import random
import httpx

RETRYABLE = {429, 500, 502, 503, 504}

async def post_with_backoff(client, url, json, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            r = await client.post(url, json=json, timeout=10.0)
            if r.status_code not in RETRYABLE:
                r.raise_for_status()   # 2xx succeeds; 4xx fails fast
                return r.json()
            # honor Retry-After on 429 if present
            wait = float(r.headers.get("Retry-After", 2 ** attempt))
        except (httpx.ConnectError, httpx.ReadTimeout):
            wait = 2 ** attempt
        wait += random.uniform(0, 1)   # jitter
        await asyncio.sleep(wait)
    raise RuntimeError(f"exhausted retries for {url}")

Async HTTP Servers

To receive webhooks and serve API endpoints, the gateway needs an HTTP server that holds many connections open without a thread per connection. That comes from the ASGI stack: a framework like FastAPI running on a server like uvicorn.

ASGI (Asynchronous Server Gateway Interface) is the standard contract between a Python web server and an async application — the asynchronous successor to WSGI, the older synchronous standard used by Flask and Django. Under WSGI, each request occupies a worker thread for its entire lifetime; handling N slow requests concurrently needs roughly N threads. ASGI removes that constraint with an async interface and natively supports WebSockets and server-sent events. Concretely, an ASGI application is an async callable receiving scope (a dict describing the connection) plus two coroutine channels, receive and send. You rarely write ASGI by hand: FastAPI is built on Starlette, which supplies routing, middleware, and WebSocket support.

Uvicorn is a lightweight, high-performance ASGI server built on asyncio. Its speed comes from two C-level libraries: uvloop, a drop-in replacement for the standard event loop that runs roughly 2–4× faster, and httptools for fast HTTP parsing. Here is a complete minimal server that verifies a Slack signature and responds:

from fastapi import FastAPI, Request, HTTPException
import os

app = FastAPI()
SIGNING_SECRET = os.environ["SLACK_SIGNING_SECRET"]

@app.post("/slack/events")
async def slack_events(request: Request):
    # Read the RAW body first — before any JSON parsing
    body = await request.body()
    ts = request.headers.get("X-Slack-Request-Timestamp", "0")
    sig = request.headers.get("X-Slack-Signature", "")

    if not verify_slack(SIGNING_SECRET, ts, body, sig):
        raise HTTPException(status_code=401, detail="bad signature")

    payload = await request.json()          # safe to parse now
    # ... hand off to a queue (Chapter 8) instead of processing here ...
    return {"ok": True}                      # fast acknowledgement

Run it with uvicorn main:app --host 0.0.0.0 --port 8000. A single uvicorn process runs one event loop on one CPU core. Concurrency is cooperative: when a handler hits an await on I/O, it yields to the event loop, which immediately runs another ready task. The critical caveat: the loop is single-threaded, so a CPU-bound or blocking call stalls every other request. This is exactly why you must use an async client like httpx inside async handlers.

To use all CPU cores and add fault isolation, run multiple uvicorn workers, commonly supervised by Gunicorn (gunicorn -k uvicorn.workers.UvicornWorker -w 4). This two-level model — async concurrency within a worker, process parallelism across workers — is the standard production deployment.

Figure 4.2: Two levels of concurrency.

Chat platforms impose tight acknowledgement deadlines — Slack expects a response within about three seconds and retries a slow reply. If your endpoint runs a slow LLM call before responding, you will blow the deadline and the retry triggers duplicate processing. The correct pattern is fast-ack: verify the signature, do the minimum work to enqueue the event, and return 200 immediately. The heavy lifting happens afterward in a background worker consuming from a queue.