Webhook reference: events, payloads, and signatures
Subscribe your systems to message and campaign events, verify signatures, and handle retries correctly.
Register a webhook
- Open Developer → Add webhook.
- Enter an HTTPS URL your server controls.
- Choose topics: messages (inbound messages and delivery status changes) and/or campaigns (lifecycle events like started, paused, completed).
- AiConva generates a signing secret for the endpoint — store it with the same care as a password.
Verify and process
Each delivery is an HTTP POST with a JSON body and an HMAC-SHA256 signature computed with your endpoint's secret. Verify the signature before trusting the payload — it proves the event came from AiConva and wasn't altered.
Respond 200 quickly (under 5 seconds) and do heavy work asynchronously. Non-2xx responses are retried with backoff, so make handlers idempotent: use the event id to drop duplicates.
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.
This guide maps directly to a screen in AiConva.