Webhook and Callback Patterns for AI
Common Mistakes
1. Not verifying webhook signatures. A webhook receiver that does not verify the HMAC signature will process fabricated payloads from any source that knows the endpoint URL. Always verify signatures.
2. Returning 200 before processing the webhook. If the webhook receiver processes the payload synchronously and takes 10 seconds, the sender's timeout may expire before it receives the 200 acknowledgment. The receiver should: (1) immediately return 200 Accepted, (2) process the payload asynchronously, (3) handle duplicate delivery via idempotency.
3. No retry policy on webhook delivery. If the receiving server is temporarily unavailable when the AI job completes, the webhook delivery fails and the result is lost. Always implement a retry policy with exponential backoff for webhook delivery.
4. Buffering SSE responses in the web framework or proxy. SSE requires that tokens are flushed immediately to the client. Framework response buffering or nginx proxy buffering accumulates tokens and delivers them in bursts rather than streaming in real time. Always set X-Accel-Buffering: no and disable framework response buffering for SSE endpoints.
Key Takeaways
- Webhooks (server push) are the preferred pattern for server-to-server AI result delivery; polling is the fallback for clients that cannot receive inbound connections
- All webhook deliveries must be signed (HMAC-SHA256) and receiving endpoints must verify the signature
- Webhook receiving endpoints must be idempotent; retry delivery means the same result may arrive multiple times
- SSE is the preferred pattern for real-time token streaming to browser-based clinical interfaces
- SSE connections require heartbeat pings at 15-second intervals to prevent proxy disconnects