Send Aiva Chat events with webhooks

A webhook tells Aiva Chat to send a signed HTTPS request to a URL you choose whenever something happens: a call ends, a lead comes in, a text arrives, an appointment is booked. You can send events to your own server, or to any automation tool that gives you a webhook URL. You need a URL that starts with https:// and can accept a JSON POST request. Everything in this guide lives under Admin & developer → Integrations in the dashboard.

1. Add a webhook

1. In the sidebar, under Admin & developer, open Integrations, then the Webhooks tab.
2. Click Add webhook.
3. Fill in the form:
   • Name: something you'll recognise later, for example "CRM sync".
   • Endpoint URL: the address that should receive events. It must start with https:// and be reachable from the internet.
   • Description (optional): a note for yourself.
   • Events: tick each event you want to receive, or use Select all. You must pick at least one.
4. Click Add webhook.
5. Aiva Chat shows Webhook added with your signing secret. It won't be shown again. Copy it and store it somewhere safe, tick I have stored this secret safely, then click Done.

Events cover calls (such as call.completed, call.missed, call.summary_ready and call.message_taken), texts (sms.received), website chat (chat.message), leads and forms (lead.created, form.submitted), campaigns (campaign.completed, campaign.failed) and support tickets.

Booking events include appointment.booked, appointment.rescheduled, appointment.cancelled, appointment.completed, appointment.confirmed and appointment.noshow, plus events for approval requests (appointment.requested, .accepted, .declined, .expired), payments (appointment.paid, appointment.refunded), repeating bookings (appointment.series_booked), cancelled class sessions (session.cancelled), the waitlist (waitlist.joined, waitlist.offered, waitlist.claimed) and passes (pass.purchased, pass.renewed and more). The Events list in the form always shows the full, current set.

Each request body is JSON with three fields: event (the event name), timestamp, and data (the details of what happened).

2. Check the signature

Every request has an X-AIVA-Signature header: a SHA-256 HMAC of the raw request body, made with your webhook's signing secret. If your receiving tool can check signatures, compare it before trusting the payload, so you can reject requests that didn't come from Aiva Chat. The How to verify a request came from us panel on the Webhooks tab has a short code example.

3. Send a test event

1. On the webhook's row, click Send test.
2. Choose an Event. The Sample payload shows the exact body that will be sent, with realistic sample data.
3. Click Send test. The result shows underneath:
   • Delivered with an HTTP 2xx code means your endpoint accepted it.
   • Failed means your endpoint answered with an error or didn't answer. Check the URL, and that it responds with a 2xx status.

If you're connecting an automation tool, send a test so the tool receives a sample to map fields from.

4. Check deliveries and retry

Click Deliveries on the webhook's row to see each delivery, its status and HTTP code, and the request body and response.

If a delivery fails, Aiva Chat retries it automatically. Your endpoint should reply quickly with a 2xx status. Anything else counts as a failure. To resend a failed delivery yourself, click Retry delivery.

A webhook that keeps failing is Paused automatically, and a banner tells you which webhooks need attention. Fix the endpoint, then switch the webhook back on.

5. Regenerate the signing secret

Click the webhook's edit button, then Regenerate next to Signing secret, and confirm. The new secret is shown once. The old secret stops working straight away, so update your receiving tool right after you regenerate.

6. Edit, pause or delete a webhook

• Pause: use the switch on the webhook's row. A paused webhook gets no events. Use the All, Active and Paused filter to find webhooks.
• Edit: click the edit button, change the fields or the Active switch, then click Save changes.
• Delete: click the delete button and confirm Delete webhook. Its delivery history is removed too. You can undo for a few seconds.

7. Manage API keys

API keys let your own scripts and other tools connect to your workspace. Treat them like passwords.

1. Open the API keys tab and click Create key.
2. Enter a Name that reminds you what the key is for, then create it.
3. Copy the key when it's shown under Copy your new key. You won't be able to see it again.

To stop a key working, click Revoke on its row and confirm. Anything using it stops working straight away, and this can't be undone.

Troubleshooting

• The URL must start with https://: change the URL to start with https://.
• Choose at least one event: tick at least one box under Events.
• Webhook URL not allowed: Aiva Chat won't send to private or internal network addresses. Use a public URL.
• A webhook shows Paused automatically: it failed repeatedly. Check Deliveries for the error, fix your endpoint, then switch the webhook back on.

Next steps

• Add custom actions so your assistant can call your own tools during a conversation.
• Connect HubSpot to log calls and contacts automatically.
• Review calls and results to see what your webhooks are reporting on.