This webhook (HTTP Push API) will ping information about your ExoPhone health every nth minute as configured. If some ExoPhones are facing connectivity issues, we will provide details about those ExoPhones alone. You can use the Get ExoPhone Details API described in next section for further connectivity information about an ExoPhone.

Description of parameters which will be set in heartbeat requests to your endpoint:

Parameter Name

Description

timestamp

This denotes the time when a particular heartbeat request was generated in our system.
Date Time Format: RFC 3339
Example: 2018-08-22T15:19:23Z

status_type

This will provide an overall state of all your ExoPhones combined. Possible values

  • OK - This denotes that all your ExoPhones are healthy and there is no connectivity issue identified by our system
  • WARNING - One or more ExoPhones' health is affected in either incoming/outgoing or both.
  • CRITICAL - All your ExoPhones health is affected in either incoming/outgoing or both
  • PAYLOAD_TOO_LARGE - It indicates that the maximum payload size limit (10MB) this method supports has breached. You may observe this error if you have signficantly large quantity of ExoPhones in your account. In case you observe this, you can use Get Exophone Details to know your ExoPhones health.

incoming_affected

Array; List of unique SIDs denoting ExoPhone(s) for which incoming call connectivity is affected

outgoing_affected

Array; List of unique SIDs denoting ExoPhone(s) for which outgoing call connectivity is affected

data

This block contains comma separated nested JSON blocks denoting information per ExoPhone which is having connectivity issues as mentioned in incoming_affected or outgoing_affected array.

phone_number_sid (key): Unique string which identifies the ExoPhone owned by you. This may not always be same as your phone number. You can find out your ExoPhone SID by triggering a GET request using your auth credentials on https://api.exotel.com/v2/accounts/<account_sid>/incoming-phone-numbers

It’s value will be a nested JSON containing below:

phone_number - Denoting the phone_number of the ExoPhone in E.164 format. This can be different than the SID of the phone number.

For example, 02030090005 denotes the phone_number_sid (key) and phone_number is present as parameter within it in E.164 format.

"02030090005":{

    "phone_number": "+912030090005"

}

Note: There could be multiple blocks depending on numbers present in incoming_affected and outgoing_affected list.

Example webhook payload with possible scenarios:

Scenario #1

If everything is working fine i.e. all ExoPhones are healthy (OK):

{
    "timestamp": "2018-08-22T15:19:23Z",	
    "status_type": "OK",
    "incoming_affected": null,
    "outgoing_affected": null,
    "data": {}
}

Scenario #2

If some ExoPhones connectivity is affected (WARNING):

{  
   "timestamp": "2018-08-22T15:19:23Z>",
   "status_type":"WARNING",
   "incoming_affected":[ 
      "07930061010"
   ],
   "outgoing_affected": null,
   "data":{  
      "07930061010":{  
         "phone_number": "+917930061010",
      }
   }
}

Scenario #3

If all ExoPhones connectivity is affected (CRITICAL):

{  
   "timestamp": "2018-08-22T15:19:23Z",
   "status_type":"CRITICAL",
   "incoming_affected":[ 
      "07930061010",
      "08030752522"
   ],
   "outgoing_affected":[  
      "07930061010"
   ],
   "data":{  
      "07930061010":{  
         "phone_number": "+917930061010",
      },
      "08030752522":{  
          "phone_number": "+918030752522",
      }
   }
}

Responding to a heartbeat request

The HTTP Response for acknowledging the heartbeat webhook request should be 200 OK. All other non-2XX HTTP codes or if your server is unable to respond timely will indicate that you have not received the heartbeat and we will retry. In such retry cases, your server should be able to handle subsequent requests of the same heartbeat and the timestamp field in the heartbeat payload can be used to uniquely identify the most recent heartbeat.

Retries and timeouts

If your server needs to perform any complex logic, or make internal network calls, it is possible that the heartbeat webhook request might time out. For that reason, you might want to have your webhook endpoint immediately acknowledge receipt by returning a 2XX HTTP status code, and then perform the rest of its operations.

Guidelines on usage

You should consume Heartbeat Webhook to continuously be aware of your ExoPhones health status and take necessary actions. In case any of your ExoPhone faces an issue as reported by webhook, you can query the GET ExoPhone Details for fetching further details. The GET endpoint can also be used to pull status per ExoPhone in case the webhook is not consumed by your servers (Exotel not being able to send or because your server is unable to process). As a best practice, polling the GET endpoint is not recommended. Exotel will throttle requests to GET ExoPhone Details endpoint with HTTP Code 429.