Use webhooks to receive real time events for your call.
call_started
: Triggered when a call starts.call_ended
: Triggered when a call ends, transferred, or errors out. The event payload includes details like the call transcript,
timestamps, and other relevant information.
disconnection_reason
to determine the call’s end reason
(hangup, or call transferred, or error).call_analyzed
: Triggered when call_analysis
object is populated in call
return object.call_ended
event. This event is triggered when a call in your Retell AI account ends.
By listening to this event, you can capture important call details like phone numbers and transcripts and perform custom actions such as logging or data analysis.
webhook_url
field.
Any event associated with that agent will be pushed to the agent webhooks url. If set, account level webhooks url will not be triggered for that agent.
POST
to the URL you provided with a JSON payload.
The payload will contain the event type and the call detail associated with the event.
It will contain a x-retell-signature
header to help you verify the webhook comes from Retell.
call
field in the webhook payload contains the call details. It’s the same content
you would receive when you fetch the call details using the get-call API.
x-retell-signature
header together with your Retell API Key to verify the webhook.
We have provided
verify function in our SDKs to help you with this.
You can also check and allowlist Retell IP addresses: 100.20.5.228
.
The following code snippets demonstrate how to verify and handle the webhook in Node.js and Python.
recording_url
field.
The link will be accessible for 10 minutes and will be
deleted and become inaccessible after 10 minutes.