### Answer When a custom function is called, Retell sends a POST request to your specified endpoint with a specific request structure [(1) ]() [(2) ]() . The request includes: Headers: - `X-Retell-Signature`: encrypted request body using your secret key -

Content-Type: application/json

Body (for POST, PUT, PATCH requests) : - `name`: the name of the custom function - `call`: the call object with context and real-time transcript - `args`: the arguments for the custom function as a JSON object If you're not receiving the JSON payload, check these common issues: 1. Payload: args only toggle - If this is enabled, the body only contains the function arguments at the top level, not nested under

args

. Disable this if you expect the full request structure with

name

,

call

, and

args

. 2. Tool registration - The custom function must be properly registered and exposed in the agent's configuration [(3) ]() . If the tool is only in the prompt but not in the config, the model may say it's calling it, but no JSON payload is emitted . 3. Webhook subscription - Ensure your webhook is subscribed to structured events (including tool calls with name + args) , not just transcript-only events . 4. Prompt instructions - Include explicit instructions in your prompt about when to invoke the custom function [(1) ]() . For example:

When user provided the city name, please get the weather for that city by calling the `get_weather` function.

5. JSON schema validation - Ensure your parameters include

"type": "object"

at the top level of the JSON schema [(1) ]() [(2) ]() . This is a common mistake that prevents the function from saving properly. To verify requests are from Retell, check the

X-Retell-Signature

header . You can also allowlist Retell's IP address:

100.20.5.228

.

​ To learn more, see the sources I considered: [[1] Integrate any system with custom function](https://docs.retellai.com/build/single-multi-prompt/custom-function) [[2] Custom Function](https://docs.retellai.com/build/conversation-flow/custom-function) [[3] Discord message from @majestic_fawn_50137 on 2025-09-17](https://discord.com/channels/1186424376300679209/1186462578310910112/1417915583340478515) ​

Feel free to tag @AI Evy with additional questions. I also appreciate feedback, it helps me improve.