Web Hooks

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

Event	Description	Payload	Additional Info
inbound_fax	A fax was received, in to Updox	{ “faxId”: 1, “”: “accountId”:””}
outbound_fax	A fax was sent, out of Updox	{ “faxId”: 1, “”: “accountId”:””, status:””}	busy, failure, received, success
inbound_mdn	A new MDN status was received, in to Updox	{ “messageId”: “”, “mdnStatus” : “”}	received, processed, dispatched, failed, deleted, denied
inbound_direct	A new Direct message was received, in to Updox	{ “accountId”:””, “userId”:””, “messageId”: “”}

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 dropped for any 4xx call, meaning we will not try to call this again.
• A call will be delayed to a separate process for any 5xx status. The process runs every 5 minutes and will try to call the url 15 times before it is permanently dropped.

Getting started

Get a list of available webhook events:

Make a POST request to https://updoxqa.com/api/io/WebHookEventList.

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". You don't have to specify the accountId, and the webhook will apply to everyone:

{
 "auth": {
   "applicationId": "<applicationId>",
   "applicationPassword": "<applicationPassword>",
   "accountId": "",
   "userId": ""
 },
 "eventId": "inbound_fax",
 "url": "http://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"
 }
}