Latest revision as of 15:00, 5 August 2020

WebHooks

What are they

A webhook is a way for a user of a system to tap into the flow, for example I can have a webhook called “inbound_fax” that would tap into to the workflow where the system receives a new fax and be notified when that happens. To actually tap into it you have to let the system know you want this information, this is done by adding a callback url (webhook) to a certain event (e.g. inbound_fax). Whenever the system receives a fax it will call this url with a preset payload (e.g. a faxId).

What events are available in Updox

How to use them

Updox needs to enable webhooks before you can use them. You can also specify an "on-the-fly" callbackUrl in the faxOemSend API (currently the only one that has this feature) that does not require Updox to enable anything for you.

There are 2 other levels of subscription to a webhook, besides the request level mentioned above. These are Practice level, and Vendor level. At the time of creating a webhook, depending on if you specify the accountId the webhook will fire for all events of that type, or just the events for that accountId.

The available webhook events are available in API WebHookEventList, to subscribe to an event you would use the WebHookSave API with the event (e.g. inbound_fax) you want and what callbackUrl you want us to call with the above payload. The auth header will determine if its tied to your vendor, or practice. If you specify an account id the webhook will be tied to that account. If you don't specify an account, it will be tied to the vendor id.

How we call the url

The initial call is made as soon as we can and make the actual HTTP POST to your specified callback url.

• A successful call is any call that returns any 2xx status.
• A call will be aborted for any 4xx call, meaning we will not try to call this again.
• A call will be retried for any 5xx status. The retry is delayed on a fibonacci scale in minutes (1,1,2,3,5,8,13,21,34, and 55). It will retry every 55min for another 15 times until it is aborted.

Getting started

Get a list of available webhook events:

Make a POST request to https://updoxqa.com/api/io/WebHookEventList with your application credentials.

{
 "auth": {
   "applicationId": "<applicationId>",
   "applicationPassword": "<applicationPassword>"
 }
}

Sample response:

{
 "successful": true,
 "responseMessage": "OK",
 "responseCode": 2000,
 "events": [
   {
     "id": "inbound_direct",
     "description": "Inbound Direct Message"
   },
   {
     "id": "inbound_fax",
     "description": "Inbound Fax"
   },
   {
     "id": "inbound_mdn",
     "description": "Inbound MDN"
   },
   {
     "id": "outbound_fax",
     "description": "Outbound Fax"
   }
 ]
}

To subscribe to incoming faxes we would create a callback url for event "inbound_fax", this url must be publicly accessible. Make a POST request to https://updoxqa.com/api/io/WebHookSave. If you want the webhook to fire for everyone you would not specify any accountId. If you want it to apply to only one account, you would.

{
 "auth": {
   "applicationId": "<applicationId>",
   "applicationPassword": "<applicationPassword>",
   "accountId": "",
   "userId": ""
 },
 "eventId": "inbound_fax",
 "url": "https://updoxqa.com/wh/callback/inbound_fax",
 "active": "true"
}

Sample response:

{
 "successful": true,
 "responseMessage": "OK",
 "responseCode": 2000,
 "webhook": {
   "eventId": "inbound_fax",
   "url": "http://updoxqa.com/wh/callback/inbound_fax",
   "active": true,
   "added_date": "2016-02-05T21:10:20Z",
   "modified_date": "2016-03-24T18:14:48Z"
 }
}

Thats it! Every time you get an incoming fax you should now get a callback to the specified URL, the payloads are specified above.

In this example you would receive a POST call to http://updoxqa.com/wh/callback/inbound_fax with the following payload:

{ 
   “faxId”: 1142, 
   “accountId”: ”<accountId>”
}