WhatsApp Business API webhooks: a developer guide for India

Webhooks are how WhatsApp tells your system about message statuses (sent, delivered, read) and inbound events (a customer replied, a button was tapped). If you're integrating the AiConva API into your own app, understanding webhooks is essential. This guide covers the practical implementation.

Receiving events

Configure your endpoint URL in the AiConva Developer page. AiConva generates a signing secret for the endpoint — store it like a password. Each delivery is an HTTP POST with a JSON body, sent to your URL with an HMAC-SHA256 signature computed with your secret. Respond 200 quickly (under 5 seconds) and do heavy work asynchronously.

Signature verification

Before trusting any payload, verify the HMAC signature — it proves the event came from AiConva and wasn't altered in transit. Recompute the signature from the raw request body using your secret and compare it to the header value using a constant-time comparison (not a naive equality check, to avoid timing attacks). Reject mismatches with a 401.

Idempotency and retries

Webhooks can be delivered more than once — network blips cause AiConva to retry. Make your handler idempotent: use the event ID to deduplicate, so processing the same event twice has no side effect. Non-2xx responses trigger retries with backoff, so a flaky endpoint will receive retries until it succeeds.

Inbound Meta webhooks (self-hosted)

If you self-host, AiConva itself receives Meta's webhooks at /api/webhooks/meta (token challenge + signed payload verification). Point your Meta App's webhook there and set META_WEBHOOK_VERIFY_TOKEN and META_APP_SECRET in the environment. Read the API documentation guide for the full event reference.