API keys and webhooks
Programmatic access to the platform, and real-time notifications when things happen on a call. Every event you can subscribe to, and what the secret is for.
6 min readUpdated 26 August 2026
Developers in the sidebar covers two things that sound similar and point in opposite directions.
| Direction | Use it for | |
|---|---|---|
| API key | You call the platform | Creating agents, reading calls, anything programmatic |
| Webhook | The platform calls you | Reacting the moment something happens on a call |
API keys
The page describes them as managing keys for programmatic access to the platform APIs. Create API Key makes one.
Treat a key as a credential, because that is what it is. Anyone holding it can act as your account.
- Store it where you store other secrets, not in a document or a message.
- Use separate keys for separate systems, so one can be replaced without breaking the others.
- Rotate rather than delete when a key may have leaked. Rotation gives you a new key without an outage in between.
Careful
Changing your account password does not affect API keys. If you are worried about a leak, do both.
Setting up a webhook
Webhook Configuration is described as setting up webhooks to receive real-time notifications about events in your account. The form has a handful of parts.
| Field | What it is |
|---|---|
| Webhook URL | Where events are sent. The page describes it as the URL where webhook events will be sent |
| HTTP Method | POST by default |
| Status | Active or otherwise, so a webhook can be paused without deleting it |
| Webhook Secret | The page describes it as the secret key used to verify webhook requests |
| Events to Subscribe | Which events you want, chosen individually |
| Custom Headers (JSON) | Optional headers sent with each request, in JSON |
| Description | Optional, for your own benefit |
The eleven events
They fall into three groups, and choosing by group is easier than picking from a list of eleven.
Tip
Subscribe to what you will act on. Agent Message and User Message fire constantly during a call, and turning them on to see what happens is how people end up with a very noisy endpoint.
| Group | Events |
|---|---|
| Call lifecycle | Call Started, Call Answered, Call Ended, Call Failed |
| What was said | Agent Message, User Message, Transcription Completed, Recording Available |
| Agent changes | Agent Created, Agent Updated, Agent Deleted |
Use the secret
The secret exists so your endpoint can tell a real request from anyone who has guessed your URL. Set it, and verify it on your side before acting on what arrives.
An endpoint that acts on anything posted to it is an endpoint anyone can drive. That is worth thinking about before you wire a webhook to something that creates records or sends messages.
Custom headers
Optional, in JSON, in the shape the placeholder shows: a key and a value, such as an Authorization header. Useful when the thing receiving your webhook expects its own token, which is common with automation platforms and API gateways.
Common questions
- What is the difference between an API key and a webhook?
- An API key lets you call the platform. A webhook lets the platform call you. Most integrations end up using both.
- Which events should I subscribe to?
- The ones you will act on. Call Ended is the common starting point, because it is when a call has a transcript and a cost. Message events fire constantly during a call and are rarely what people actually want.
- Do I have to set a webhook secret?
- It is what lets your endpoint verify the request came from us. Without it, anything that knows your URL can post to it.
- Can I pause a webhook without deleting it?
- Yes, that is what the Status field is for.
- I rotated my API key. What breaks?
- Anything still using the old one. That is why separate keys for separate systems is worth the small extra effort.
Was this helpful?