Webhook Endpoint Guidelines (Asynchronous Processing)
Webhook endpoints must be designed to receive and acknowledge requests quickly. Webhooks are not meant to perform heavy processing synchronously.
Failure to do so may result in delayed retries, duplicate deliveries, or missed events.
Why Webhook Endpoints Must Be Asynchronous
WhatsApp and Cunnekt expect your webhook endpoint to:
- Accept incoming webhook requests
- Respond with 200 OK immediately
- Process the payload outside the HTTP request lifecycle
If your endpoint:
- Performs database writes
- Calls external APIs
- Runs business logic synchronously
it may exceed timeout limits and cause the webhook to be retried.
What Your Webhook Endpoint SHOULD DO
- Accept POST requests
- Validate payload structure
- Acknowledge the request quickly (< 1 second)
- Store or enqueue the payload for background processing
- Handle duplicate webhook deliveries safely
What Your Webhook Endpoint SHOULD NOT DO
- Perform long-running tasks
- Call third-party APIs synchronously
- Block on database transactions
- Assume webhooks are delivered only once
- Return delayed or non-200 responses