Configurable Callback Retries

    Overview

    Plivo sends HTTP webhooks as callbacks during different states of a call and to many URLs, such as answer_url, fallback_url, hangup_url, action, and callback_url. Whenever a failure happens (possibly due to some network issue at the destination server) Plivo retries to send the callback payload to the URLs. For maximum flexibility with webhook callback requests, Plivo offers you configurable retry policies on our Voice platform. You can set this feature to take over when a webhook request fails due to some destination server issue. This tutorial guides you through the timeout and retry settings for the configurable webhook URLs.

    Note: If you don't customize timeout and retry configurations, Plivo will use the default duration set for the retry policy.

    Callback Retry Scenarios

    Having the ability to configure callback retries and timeouts improves reliability and event recovery by letting you:

    1. Configure a custom timeout based on your use case
    2. Set higher timeouts during network problems on your application server
    3. Set shorter timeouts during an outage on your application server to ensure faster failover to fallback URL
    4. Enable retries during client-side service interruptions and delays

    Configuration Mechanism

    To set a nondefault callback retry configuration for any given URL (answer URL, fallback URL, ring URL, etc.), you need to append relevant configuration parameters to it in the form of URL extensions (or ”fragments”) as key-value pairs implemented as follows:

    • the first key-value pair should start with #
    • key and value should be separated by =
    • the key-value pairs should be separated by &

    URL Format

    https://example.com/answer_url?query=123#param1=2500&param2=5500
    
    Note: If you don't append any parameter, default values will apply as specified in the tables below.

    Timeouts

    When Plivo sends HTTP callbacks to your webhook URLs during events, 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 the HTTP 200 status code is not returned. The overall timeframe Plivo has to wait to receive the response from your application server is called timeout.

    You can find the different timeouts available for the webhook URLs and their respective allowed values and default values in this table:

    ParamNameDescriptionValidationsDefault
    ctConnection timeoutThe time in milliseconds (ms) for Plivo to wait for establishing the TCP connection

    Min: 100

    Max: 10000

    2000
    rtRead timeoutThe time in milliseconds for Plivo to wait:

    — to start receiving a response after sending the initial request

    — for delay between packets

    Min: 100

    Max: 40000

    40000
    ttTotal timeoutUpper limit on total time allowed for all timeouts including retries on a given URL (not including fallback URL)

    Min: 100

    Max: 55000

    55000

    Examples

    1. https://example.com/answer_url?query=123#ct=2000
      Connection timeout of 2 seconds

    2. https://example.com/answer_url?query=123#ct=2000&rt=3000
      Connection timeout of 2 seconds and a read timeout of 3 seconds

    Retries

    Plivo provides the option to configure the number of retries it makes for different webhook URLs and the policy it should use depending on HTTP failure status codes:

    ParamNameDescriptionValidationsDefault
    rcRetry countNumber of retry attempts to be made to the same URL if the initial connection fails (not including to fallback URL)Min: 0Max: 51
    rpRetry policyType of failure to retry on:

    4xx → only on 4xx responses

    5xx → only on 5xx responses

    ct → TCP/TLS connection failures within the connection timeout

    rt → no response received within the read timeout

    all → all the above

    comma-separated list of values — for example, rp=ct,rtct,rt
    Note: If a partial response is received from your app server, no retry attempt will be made from Plivo.

    Examples

    1. https://example.com/answer_url?query=123#rt=3000&rp=ct,rt
      Retry on both connect and read timeout, also reduce the read timeout to 3 seconds

    2. https://example.com/answer_url?query=123#rc=3&ct=2000
      Retry on connection failure, but with a two-second connection timeout. If there is no connection in 2 seconds, retry three times, for a total of four attempts to connect.

    Applicable URLs

    Here’s the list of URLs associated with Plivo’s Voice application on Console, API requests, and XML elements that apply to callback retries:

    Voice Application on Console

    • Primary Answer URL
    • Fallback Answer URL
    • Hangup URL

    API

    Make Call:

    • answer_url
    • ring_url
    • hangup_url
    • fallback_url
    • machine_detection_url

    Transfer Call:

    • aleg_url
    • bleg_url

    Record Call:

    • transcription_url
    • callback_url

    Record Conference:

    • transcription_url
    • callback_url

    XML

    Dial:

    • action
    • confirmSound
    • dialMusic
    • callbackUrl

    Conference XML:

    • action
    • callbackUrl
    • waitSound

    GetInput:

    • action
    • interimSpeechResultsCallback

    GetDigits:

    • action

    Record:

    • action
    • transcriptionUrl
    • callbackUrl

    Redirect

    Inapplicable URLs

    Callback retry parameters are not applicable to any of the following audio URLs:

    API

    Play audio on a call
    Play audio to a conference member

    XML

    PreAnswer XML
    Play XML

    These URLs use our standard configuration values:

    • Connection timeout: 2 seconds
    • Read timeout: 120 seconds
    • Retry count: 1
    • Retry policy: all