Callbacks

Using Verify APIs, you can send requests to your users through SMS or voice channels. You can use event-based webhooks — user-defined HTTP callbacks — to track the delivery status of your requests. Plivo sends a status update to a URL you configure as a callback. You can store the information on your server for delivery status analysis. To handle a webhook, you must create a listener (web app) that can accept these HTTP requests from Plivo.

Setting up webhooks

Code

1
2
3
4
5
6
7
8
9
10

curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{ 
     "app_uuid":"<app_uuid>",
    "recipient": "<recipient>",
    "url":"https://<yourdomain>.com/sms_status/",
    "channel":"sms",
    "method":"POST"
}' \
    https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/
Notes:
  • Replace the auth_id and auth_token placeholders with your authentication credentials, which you can find on the Overview screen of the Plivo console.
  • Replace the app_uuid placeholder with the application that you created and recipient with the phone number you’ll be sending your OTP to. recipient should be in E.164 format.
  • Replace channel placeholder with the channel that you wish to use - either sms or voice
  • Replace https://<yourdomain>.com/sms_status/ with the webhook URL you’ve set up.

Handle callbacks in your web app

To handle callbacks in your app, your endpoint should capture HTTP requests and respond to them.

When Plivo sends the HTTP request callbacks to the 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. You can store the callback data to your database.

Note: Plivo automatically retries webhooks three times if an HTTP 200 status code is not returned:
  • First at 60 seconds after the original attempt.
  • Second at 120 seconds after the first retry attempt.
  • Third at 240 seconds after the second retry attempt.

Test and validate

Let’s look at an example. Typically, you would include a URL that points to your web app, but we’ll use a URL from RequestBin, a service that lets you collect, analyze, and debug HTTP requests, so we can check the callbacks.

  • Create a new bin in RequestBin.
  • Replace the “url” placeholder with the URL of the new bin.
  • Run the code that appears above. You should receive the SMS message on the phone number defined in the destination field, and see callback requests in RequestBin similar to the screenshots below for callback events such as queued, sent, and delivered.

Callback format

Plivo sends the following fields to your application:

  • SessionUUID: Unique identifier for you sessions
  • SessionStatus: Status of the session; either in-progress, verified, or expired
  • RequestTime: Time when this attempt was made
  • Recipient: Number of the recipient
  • ChannelErrorCode: Error code for the channel
  • Channel: Channel used
  • AttemptUUID: Unique identifier for each attempt
  • AttemptSequence: Sequence number of this attempt in a session
  • ChannelStatus: Status of your attempt, which can take different values depending on the channel
    • SMS: sent, delivered, failed, undelivered
    • Voice: in-progress, completed, no-answer

Validating callbacks

To avoid spoof attacks, you can validate the callbacks that your server URL receives. All requests made by Plivo to your server URLs include X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2, and X-Plivo-Signature-V2-Nonce HTTP headers. You can use them to validate that a request is from Plivo, as we discuss in our signature validation guide.