Skip to main content
Use Webhook to preload external data for an inbound call. For example, a CRM or routing service can send the caller’s account status, preferred language, or support tier so the flow can personalize the greeting or choose a route without collecting the same information. Webhook runs only in pre-call on inbound flows. Use API Request when the flow should request data from an external service as it runs.

​
How Webhook works

Your external system sends an authenticated POST request to the generated webhook URL. Phonely stores the payload for the specified agent and caller phone number. When an incoming call matches that agent and phone number, the Webhook block loads the payload before the flow trigger runs. Fields discovered during a successful block test become variables for the trigger and later blocks. Send the request before the call reaches Phonely whenever possible. If the request and call may arrive at nearly the same time, configure a short fallback wait.

​
Send data to the webhook

Open the block’s Configure step to copy its webhook URL, API key, or sample cURL command. Send a POST request with a JSON body and the API key in the X-Authorization header. The request body requires: Add each value you want to use in the flow as another top-level field:
Use the caller’s actual phone number, including its country code. Additional field values must be text, numbers, booleans, or null; nested objects and arrays are not accepted.
Keep the API key private. Do not include it in documentation examples, screenshots, shared logs, or Ask AI prompts.

​
Test and create variables

The block test discovers the payload fields and creates variables for later blocks to use.
  1. Open the Test step and select Test.
  2. Within one minute, send a POST request to the webhook using representative field names and safe sample values.
  3. Confirm that the fields appear under Fields from the webhook.
A successful test creates variables under the block’s name. Later blocks can select them from Available Variables. If the payload fields change, run the test again and review any downstream fields that reference the Webhook variables.

​
Configure the fallback wait

Under Advanced Settings, Time Wait Before Fallback controls how long the block checks for data after the call begins:
  • At 0 seconds, the block checks once and continues immediately if no matching payload is available.
  • From 1 to 5 seconds, the block continues checking for the payload until the configured time expires.
Keep this value as short as possible because the caller waits before the flow trigger begins. If no matching payload arrives in time, the flow continues without values from that request.

​
Verify the live behavior

Use a phone number you control:
  1. Send the payload with the agent’s ID and the phone number you will call from.
  2. Place an inbound call to the agent from that number.
  3. Confirm that the flow follows the expected route and that later blocks receive the Webhook values.
Test both a matching payload and a call with no matching payload, especially when the flow uses Webhook data for routing.

​
Troubleshooting

Select Test before sending the request and send it within one minute. Confirm that the request uses POST, includes the copied API key in X-Authorization, and contains both agentId and phoneNumber.
Include the field in a successful block test. Use a top-level field with a text, number, boolean, or null value; nested objects and arrays are not accepted. If the field set changed, test again and update any affected references.
Confirm that agentId identifies the agent receiving the call and that phoneNumber matches the number used to place it. Send the payload before the call, or increase Time Wait Before Fallback slightly when the two events can occur at nearly the same time.
Reduce Time Wait Before Fallback or send the payload earlier. Use a nonzero wait only when the external system cannot reliably send the data before the call starts.
Last modified on July 17, 2026