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.
HTTP POST method is used for heartbeat requests and each request will be issued with the Content-Type header application/json
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. |
|
status_type |
This will provide an overall state of all your ExoPhones combined. Possible values
|
|
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",
}
}
}
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.
Default Timeout = 15 seconds (Your servers should ideally consume heartbeat within milliseconds, but Exotel will wait maximum of 15 seconds for your endpoint to consume heartbeat and return 2XX HTTP code)
Retries = 2 (Exotel will retry twice in case of timeout or non-2XX HTTP code)
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.
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.
