Web Hooks
Contents |
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
To enable Webhooks, there is a feature "webHooksEnabled" that must be set. You can also specify an "on-the-fly" callbackUrl in the faxOemSend API (currently the only one that has this feature).
There are 2 other levels of subscription to a webhook, besides the request level mentioned above. These are Practice level, and Vendor level.
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. When we reach the desired point in the workflow we push the event to a queue "WebHookNotifyHandler" that will pick it up and make the actual HTTP call (POST).
* 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.
