Webhook Spec
The webhook willPOST
the payload to your endpoint. The webhook has a timeout of 10 seconds. If within 10 seconds no success status (2xx) is received, the webhook will be retried, up to 3 times.
The webhook can be verified using your Retell API Key to make sure it comes from Retell AI. Read more at Secure the webhook.
Request payload
These fields might be provided in the payload depending on your configuration:agent_id
: if the number has inbound agent id set, you will see it in payloadfrom_number
: this will always show up in payload, helps you identify the caller and process the call accordinglyto_number
: this will always show up in payload, helps you identify the receiver and process the call accordingly
Response
We expect a JSON response with a successful status code (2xx) with fields grouped undercall_inbound
. Here’re the allowed fields (all of them are optional):
override_agent_id
: if you want to override the agent id, you can set it hereoverride_agent_version
: if you want to override the agent version, you can set it heredynamic_variables
: if you want to set dynamic variables for this inbound call, you can set it heremetadata
: if you want to set metadata for this inbound call, you can set it here
FAQ
What would happen to the call when the webhook response is not received yet?
What would happen to the call when the webhook response is not received yet?
The call would continue to stay in ringing state.
What would happen if webhook was not successful?
What would happen if webhook was not successful?
It would get retried up to 3 times. If all of those attempts fail, it will check whether this number has an inbound agent id set. If it does, it will then try to connect the call to that agent. If not, it will then disconnect the call.
Can I use this webhook to decline inbound calls based on caller number?
Can I use this webhook to decline inbound calls based on caller number?
Yes, you can. To selectively reject some inbound calls:
- Unset the
Inbound Call Agent
in the phone number setting - Enable the
Inbound Webhook
- Listen to webhook request body call_inbound.from_number
- If you want to pick up the call, respond with a 200 status code containing the “call_inbound.override_agent_id” as a JSON object.
- If you want to reject the call, respond with a 200 status code without containing the “call_inbound.override_agent_id” as a JSON object.