API Architecture and Integration Design · API Styles and Contracts
GraphQL and Webhooks
When GraphQL fits, how to secure it, and how to design outbound webhooks.
GraphQL lets clients request exactly the fields they need from a typed schema — great for diverse frontends and aggregating data — but needs DataLoader batching (N+1), query depth/complexity limits, persisted queries, and field-level authorization. Webhooks push events to subscribers: sign payloads (HMAC with timestamp), include an event ID for deduplication, retry with backoff for days, isolate slow endpoints, and offer a delivery log and replay.
POST https://customer.example.com/hooks/acme HTTP/1.1
Content-Type: application/json
Webhook-Id: evt_01J9ZK...
Webhook-Timestamp: 1791623564
Webhook-Signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{"type":"order.paid","data":{"order_id":"ord_8812","amount":2400,"currency":"EUR"}}
Common pitfalls
- GraphQL without complexity limits (expensive queries as DoS).
- Webhooks without signatures or replay protection.
- Treating webhook order as guaranteed.
Key points
- GraphQL: flexible queries, needs batching and limits
- Webhooks: sign, dedupe, retry, log
- Standard Webhooks spec for consistency
Further reading: Standard Webhooks
Practice questions
What is the N+1 problem in GraphQL and how is it solved?
Answer
Resolving a field per parent item triggers one query per item; DataLoader batches and caches loads within a request into a single query.
Why include a timestamp in webhook signatures?
Answer
Receivers can reject old messages, preventing replay of captured requests.
Open in the app to mark lessons complete, take notes and track your progress.