Calendars, CRMs, helpdesks, commerce platforms, messaging tools — the integrations list covers most of what a business connects AIVA to. Most isn't all. Webhooks are how AIVA reaches whatever isn't on that list: an internal tool, your own database, a Slack channel your CRM integration doesn't know about, anything with a URL you control.
One thing worth being direct about upfront: this isn't a general-purpose API. You can't reach into AIVA and pull arbitrary data on demand. What you get is narrower, and for most of what people actually want, more useful — AIVA tells you the moment something happens, instead of you having to go ask.
How it actually works
You register a URL. AIVA sends a POST request with a JSON body to that URL the moment a specific event happens — a booking gets created, a conversation gets escalated to a human, a new contact comes in. No polling, no scheduled job checking whether anything changed. Here's what a real booking.created payload looks like:
POST https://your-app.com/aiva-webhook
{
"event": "booking.created",
"channel": "voice",
"language": "hi-IN",
"customer": { "phone": "+9198XXXXXX17" },
"booking": {
"at": "2026-06-26T10:30:00+05:30",
"service": "Consultation"
}
}
Other events — a hand-off to a human, a new contact captured — follow the same shape: an event field identifying what happened, plus whatever context is relevant to that event.
The events you can actually subscribe to
It's worth laying these out plainly rather than leaving them implicit in a single payload example:
| Event | Fires when | Typical use |
|---|---|---|
booking.created | A new appointment is booked, on any channel | Sync to an internal system, trigger fulfillment |
| Hand-off to a human | A call or chat escalates and a person needs to step in | Alert a Slack channel, page whoever's on call |
| New contact captured | A new customer contact comes in | Add to a CRM or outreach list not already integrated |
Each one carries the context relevant to that specific event rather than a generic dump of everything AIVA knows — a booking.created payload carries booking details, not the full conversation transcript, keeping the payload focused on what an endpoint actually needs in order to act.
Verifying it's actually us
Every webhook request carries a signature header so your endpoint can confirm the payload wasn't forged. We renamed this header earlier this year — it's X-Aiva-Signature now, having previously shipped as X-Signature — and ran a 90-day window where both worked, specifically so nobody's integration broke without warning. If you built against webhooks before that migration finished, it's worth double-checking you're reading the current header.
Check the signature before you trust the payload. This matters more than it sounds like it should — anyone who finds your endpoint URL can POST a fake booking.created to it if you're not verifying who actually sent it.
Building for how webhooks behave
A few things worth designing for, not because AIVA is unusual here but because most webhook systems share them:
- Return quickly. Acknowledge the request and do slow work — writing to a database, calling another API — asynchronously, rather than making AIVA wait on it.
- Expect duplicates. Treat delivery as at-least-once, not exactly-once. If your endpoint isn't idempotent, a redelivered event can double-book or double-log something. Keying off an event ID to detect repeats is the usual fix.
- Fail loudly, not silently. If your endpoint is down, you want to know about it — check your logs rather than assuming silence means nothing happened.
None of these are exotic engineering requirements. They're the same discipline any team building against any third party's webhooks would want anyway — AIVA's aren't asking for anything a well-built endpoint shouldn't already be doing.
The idempotency point is the one people skip until it costs them something. Picture an endpoint that writes a new row to an internal spreadsheet or database every time it receives a booking.created event, with no check for whether that booking was already logged. A network hiccup causes AIVA to redeliver the same event once, and now there are two rows for one real appointment — not because anything failed, but because "at-least-once" delivery was treated as "exactly-once" by the code on the receiving end. Keying writes off the event's own ID, and treating a repeat as a no-op rather than a fresh write, is a small amount of extra code that prevents a class of bug that's genuinely annoying to notice after the fact, since the data looks plausible right up until someone reconciles it against the real calendar.
Webhooks aren't a substitute for a public API — on purpose
It's worth being explicit about the boundary, because "webhooks" and "API" get used loosely enough that the distinction blurs. A webhook is one-directional and event-shaped: AIVA tells you when something happened. You can't use a webhook to ask AIVA a question on demand — query a customer's booking history, pull a list of today's conversations, look something up outside the moment an event actually fires. That's what a general-purpose API would let you do, and we've written separately about why AIVA doesn't have one of those yet: a public API is a permanent versioning commitment the moment external developers build against it, and we're not there yet on either our data model's stability or the dedicated capacity it would take to support one properly. Webhooks are a narrower, more contained promise we can make responsibly today — notify you when something happens, in a fixed, versioned shape — without taking on the much larger commitment of letting anyone query AIVA's internals however they want.
Where it's configured
Webhooks and external-tool API keys both live under Settings → Developer in the dashboard. The API keys are the other half of "connect anything" — where webhooks push events out to you, stored keys let AIVA call out to an external tool that isn't on the standard integrations list, if that's what a conversation needs.
What people actually build with it
The pattern we see most: piping every conversation into an internal database or data warehouse the moment it ends, for teams that want their own copy of the data rather than relying on the dashboard. After that, custom alerting — a hand-off notification into a tool that isn't Slack or Teams, kicking off an internal fulfillment step the moment a booking lands, or feeding a nightly reconciliation job that isn't worth a dedicated integration for.
None of these are exotic. They're the kind of thing a single engineer builds in an afternoon once the event is actually arriving — which is the whole point of a webhook over asking us to build a bespoke integration for a workflow only one customer has. It's the same reasoning behind how Twilio fits into AIVA's own stack: a well-defined event boundary lets each side do its own job without either one needing to understand the other's internals.
Webhooks versus the simpler options
Not every business that wants "AIVA's data somewhere else" needs a webhook. If the actual goal is a person looking at rows in a familiar tool, Google Sheets is a simpler fit — no endpoint to build or maintain, no signature to verify, just a spreadsheet that fills itself in. Webhooks earn their extra complexity when something needs to happen automatically the instant an event fires — a database write, an alert, a fulfillment step — not just when someone wants to look at the data later. If you're not sure which one you actually need, the honest test is whether a human is expected to act on the data, or a system is.
Where to go from here
Full request and payload examples are in the webhook docs. If what you need doesn't fit a webhook either, talk to us — sometimes the answer is a new item on the integrations list instead, and sometimes it's a simpler export that fits the need better than an endpoint you'd have to build and maintain yourself.