Webhooks, Async Operations and Performance

Sending webhooks

Webhooks notify other systems when something happens (order.paid, project.published).

{
  "id": "evt_9a8b7c",
  "type": "order.paid",
  "created_at": "2026-10-21T09:30:00Z",
  "data": {"order_id": "7", "amount": 4900, "currency": "usd"}
}

• Sign each payload with an HMAC of the body using a per-subscriber secret, sent in a header, so receivers can verify it came from you.
• Include a unique event ID so receivers can ignore duplicates.
• Retry failed deliveries with exponential backoff, and let subscribers see delivery logs.
• Send from a background worker, never inside the user's request.

Receiving webhooks

Verify the signature with a constant-time comparison, respond quickly with 2xx, process in the background, and make processing idempotent (store processed event IDs).

Long-running operations

For work that takes longer than a request should (report generation, video processing):

POST /v1/exports           -> 202 Accepted, {"id": "exp_1", "status": "queued"}
GET  /v1/exports/exp_1     -> {"status": "running", "progress": 40}
GET  /v1/exports/exp_1     -> {"status": "done", "download_url": "..."}

Optionally notify completion with a webhook.

Caching

• HTTP caching: send ETag or Last-Modified; clients send If-None-Match and get 304 Not Modified with no body.
• Server caching: cache expensive, rarely changing reads (Redis or Flask-Caching) and invalidate on writes.
• Never cache personalised responses in shared caches: Cache-Control: private, no-store.

Performance checklist

• Index every column used for filtering and sorting.
• Avoid N+1 queries when serialising related objects.
• Paginate everything that returns lists.
• Compress responses (gzip/brotli at the proxy).
• Set timeouts on every outgoing HTTP call.
• Measure: log response times per endpoint and watch the slowest.

Exercise

Add an order.paid webhook to your API: subscribers register a URL, deliveries are signed and retried with backoff from a worker, and a delivery log shows each attempt. Write a tiny receiver that verifies signatures and ignores duplicates.

Check yourself

• Why must webhook payloads be signed?
• How should an API handle a 5-minute export?
• Which responses must never be cached by shared caches?