Webhooks and delivery log

What it is for

A webhook reports events from EasyUC to another system. As soon as an end user, a phone, a device profile, a voicemail box or an enduser task is created, changed or deleted, EasyUC sends a POST request with the details to the stored address.

Typical recipients are ticket systems and inventory or billing systems. EasyUC logs every delivery with request, response and response code. If a delivery fails, EasyUC tries again, up to eight times in total.

Prerequisites

An account with the access type Administrator (full access) (ROLE_APP_ADMIN) or the owner account (ROLE_OWNER). Only these accounts see the Administration menu.
An address of the recipient that accepts POST requests and can be reached from the EasyUC server.
For HTTPS, a certificate of the recipient that the EasyUC server trusts.
If the recipient requires authentication: user name and password for Basic Auth.
For error mails: e-mail delivery that has been set up.

Step by step: creating a webhook

Open the EasyUC Cisco workspace.
Select Administration → Integrations & Communication → Webhooks.
Click Add Webhook at the top right.
Under Payload URL, enter the address of the recipient, for example https://tickets.intern/hooks/easyuc.
Under SSL verification, leave the selection Enable SSL verification as it is.
If the recipient requires authentication, switch on Credentials (Basic Auth) and fill in Username, Password and Retype Password.
Under Add email addresses (type an e-mail address and press enter), enter the addresses that are to receive a mail in the event of a delivery error.
Under Which events (actions) would you like to trigger this webhook?, select either Send me everything or Let me select individual actions and then tick Create, Update and Delete for each object.
Under To which CUCM connections would you like to apply this webhook?, select either All or Select connections and then the clusters under Connections.
Click Create. The webhook appears in the list with the badge enabled and the note This hook has never been triggered.

Step by step: checking delivery

Trigger a matching event, for example by changing a test user.
In the row of the webhook, click Actions → Audit Logs.
Read the column Event Status: pending, processing, success or error, together with the response code of the recipient.
In the row, click View → Request sent to see the transferred data.
Click View → Response received to see the response of the recipient.

Step by step: changing, switching off or deleting a webhook

In the row, click Actions → Update. The window Update Webhook opens.
To switch it off temporarily, switch off Enable. The remaining fields disappear and the settings remain stored.
If required, change the address, events or connections and click Update.
To remove it, select Actions → Delete and confirm the prompt Are you sure?.

Fields and options

Fields and options
Field / action	Meaning and use
Enable	Only when editing. Off: the webhook sends nothing. New webhooks are enabled.
Payload URL	Address to which EasyUC sends the POST request.
SSL verification	Enable SSL verification (default) verifies the certificate of the recipient. Disable (not recommended) switches the verification off.
Credentials (Basic Auth)	Switch Enabled or Disabled. On: EasyUC authenticates to the recipient with Username and Password. Default: off.
Add email addresses	Recipients of a mail in the event of delivery errors. Several addresses are possible; complete each one with Enter.
Send me everything / Let me select individual actions	Default: Send me everything. With individual selection, the object groups appear.
Enduser	Create, Update, Delete and Auto Delete (compact info) for users removed by the automatic cleanup.
Voicemails	Create, Update, Delete for voicemail boxes.
Phones	Create, Update, Delete for devices.
Device Profiles	Create, Update, Delete for device profiles.
Enduser Tasks	Create and Delete. In addition the choice Send full task info (default) or Send compact task info.
All / Select connections	Default: All clusters. With a selection, only events from the selected connections.
Redelivery (delivery log)	Shows true if the entry is a further delivery attempt, otherwise false.
Created At / Delivered At	Time of the event and of the successful delivery. Below it, where applicable, sent after <number> attempts or not delivered after 8 attempts.

Checking the result and narrowing down errors

Success: the delivery log shows success with the response code of the recipient and a time under Delivered At.
Status error with a response code of 400 or higher: the recipient rejected the request. Check the address, the credentials and the response under Response received.
Status error without a usable response code: EasyUC cannot reach the recipient or does not trust the certificate. Check name resolution, firewall and certificate chain. Do not switch SSL verification off permanently.
Status pending (after <number> attempts): EasyUC is trying the delivery again. After eight attempts, not delivered after 8 attempts is shown.
The recipient has to be able to handle the same event arriving several times.
No entry is created: the event does not match the selection of actions or connections, or the webhook is disabled.