Webhook reference: events, payloads, and signatures

Register a webhook

1. Open Developer → Webhooks → Add an endpoint.
2. Enter an HTTPS URL your server controls (plain http, localhost and private addresses are refused).
3. Tick the events you want: message.received, message.status, contact.created, contact.opted_out, campaign.completed.
4. Copy the signing secret (whsec_…) when it appears — it is shown once. Press Send test to see a signed event arrive before you rely on it.

Verify and process

Each delivery is an HTTP POST with a JSON body and an X-AiConva-Signature header of the form t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>" using your endpoint's secret. Verify it against the raw body, compare in constant time and reject timestamps older than five minutes; the Developer page's API reference has Node.js and Python examples.

Respond with any 2xx within 8 seconds and do heavy work asynchronously. Anything else, including a timeout or a redirect (redirects are never followed), is retried after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours. If five events in a row use up every attempt the endpoint is turned off and you are alerted in the console; fix it and press Resume. Retries mean you can receive an event more than once, so make handlers idempotent using the event's id.

Inbound Meta webhooks

Separately, AiConva itself receives Meta's webhooks at /api/webhooks/meta (verify token challenge + signed event payloads). If you self-host, point your Meta App's webhook there and set META_WEBHOOK_VERIFY_TOKEN and META_APP_SECRET in the environment.