Plivo makes HTTP requests to webhooks during different states of a voice call. These callbacks can help you analyze the call statuses of an ongoing call and manage call flow based on the values you receive from callback events.
Webhooks are user-defined event-based HTTP callbacks that operate based on the concept of event reaction. They’re a helpful tool to use when you want to create instant and real-time notifications.
Plivo uses webhooks to make it possible to track the status of your voice calls. For every outbound and inbound call, Plivo sends a status update to a URL you configure for receiving callback events. You can read and store the information on your server for call reporting analysis.
When a webhook is triggered by an event, Plivo makes an HTTP request (POST or GET) to the endpoint URL configured for the webhook. To handle a webhook, you must create a listener (web application) that can accept these HTTP requests.
For outbound calls from your web application, you can use callbacks to manage the call flow and receive status events on your application server. Plivo uses webhook callbacks in both Voice API and XML elements:
Webhook parameters associated with a Voice API outbound call payload are answer_url, ring_url, fallback_url, and hangup_url. answer_url is a mandatory parameter for outbound API calls; the others are optional. You can configure unique webhook URLs and set the method as either POST or GET to receive call status-related callbacks during different events.
answer_url : When a call is answered by the destination number, you can control the call flow with the help of the answer_url set in the API request. Plivo invokes the answer_url specified as soon as the call is answered and expects a valid XML response with instructions to handle the call. To see how this works, you can use https://s3.amazonaws.com/static.plivo.com/answer.xml as answer_url to test your first outgoing call:
<Response> <Speak>Congratulations! You've made your first outbound call!</Speak> </Response>
This XML snippet gives instructions to say, “Congratulations! You’ve made your first outbound call!” to the call recipient.
Plivo can also send parameters with an HTTP request during other events of a call so your application can act to continue the call flow or to change it based on the values it receives. For information about the parameters Plivo sends to these URLs and the possible values they can contain, refer to the Callbacks section under Make an outbound call in our Voice API Reference documentation.
The URLs most commonly associated with an XML response from the answer_url are action and callbackUrl.
For more information about the callback parameters sent to action and callbackUrl, refer to the XML elements sections in the XML reference documentation for elements such as Conference, Dial, GetInput, and GetDigits.
You can use webhooks with Plivo numbers to receive callbacks for incoming calls. When a voice-enabled Plivo phone number receives an incoming call, Plivo sends an HTTP request callback (either POST or GET depending on the method set for the webhook) to the URL specified in the application.
In the callback, all the information related to the inbound call is either in the POST request’s body or the GET request’s query parameters. Here are details about the URLs associated with an inbound call to a Plivo number:
The URLs associated with API payload are Primary Answer URL, Fallback Answer URL, and Hangup URL.
For more information about the parameters you can send to these URLs and the possible values they can contain, refer to the XML request section of our XML Reference documentation.
The URLs associated with the XML response from the answer_url are action and callbackUrl.
Check the receive an incoming call guide for more information about how to receive an incoming call on a voice-enabled Plivo phone number.
To handle callbacks in your application, your endpoint should capture HTTP requests and respond to them.
When Plivo sends HTTP request callbacks to a webhook during an event, you should capture the request (POST or GET based on the type you’ve defined for the URL) and respond with a 200 OK response. To process the callback, you can store the data in your database.
Plivo automatically retries webhooks for a certain timeframe if an HTTP 200 status code is not returned. Check the Configurable Callback Retries guide for more information about callback timeouts and retries.
To avoid spoof attacks, you should validate the callbacks that your server URL receives. All requests made by Plivo to your server URLs include X-Plivo-Signature-V3, X-Plivo-Signature-Ma-V3, and X-Plivo-Signature-V3-Nonce HTTP headers. You can use these signatures to validate that the request is from Plivo. Read more about signature validation in our Signature Validation guide.