Configuring Webhooks

Summary

Webhooks allow for external applications to listen for events that are occurring within EngageIP. They facilitate easier integration with EngageIP and remove the requirement to poll EngageIP's data, providing instant notifications of completed events. They also provide a mechanism to decouple business-specific logic and processes from the inner workings of EngageIP, allowing integrations to be developed in the language and on the platform of choice.

Webhooks Functionality

Webhooks are signals that send out an HTTP request with a payload in a POST operation when events fire at an entity level. When an event occurs, and it is setup as a queueable event, it is added to the webhooks event queue and is eventually processed by the Webhooks. The Webhooks notifies an HTTP endpoint, that is setup to handle the event, that the event has occurred and what entity was acted upon.

Entity Events
Entity Events tell the system what events it should capture when they occur. Whenever an Entity is Created, Updated or Deleted an event is passed through EventLogger.Log(). There, it looks at a cache of the Entity Events table to see if it should process the event or not. If the event should be handled, it creates a new WebhookActivity in the WebhookActivity table.

Requirements

1. The EngageIP Webhook must be running in Windows for Webhooks to function as described above

2. EngageIP 9.3.2 or earlier: Domain Model Logging must be enabled (found on the Configuration page in EngageIP). This setting does not need to be enabled for systems running EngageIP 9.3.3 or later versions

   Open

   

3. Webhooks will only fire on objects that have a valid OwnerId or UserId

Configuration

Configuration File

The Configuration file for the Webhook can be found in your EngageIP install path (typically C:\Program Files(x86), under the EngageIP\Services path. The file name is WebhookService.exe.config. Within the file you can change the Queue Polling Time (default is every 5 seconds). The polling time value determines how often the Webhook Activity Table is polled.

Creating an Entity Event

1. In the AdminPortal load on the Setup page

2. Click on Entity Events

3. Click the Add button

4. The Add Entity Event page will load, shown below

   Open

   

   • Select an Entity (for example UserPackage)

   • Select an Action (for example Update)

   • Enter a Description of the Event (optional)

   • Check Enabled

5. Click the Save button when finished, or Save/New to add another Entity Event

Registering Webhooks

The Webhooks needs to know what to do with WebhookActivites in queue. Webhook Registrations specify what URI to send the event to.

1. Load on the Setup page

2. Click Webhook Registration

3. On the Webhook Registration page that loads click the Add button

4. The Add Webhook Registration page will appear, shown below

   • Select an Entity/Action to handle

   • Enter the URI to POST to

   • Check Is Enabled to Enable the Registration

   • Check Sends Json to include JSON of the Entity, Action and the Object in the POST request

5. Click the Save button when finished, or Save/New to add another Webhook Registration

Webhook Activity

A Webhook Activity is a queued event that holds the information about an event that has occurred in the system and the request state.  It contains the dates of when the event occurred, when it was last tried and when it will be tried next.  It also contains information about the Entity, and the Object that was generated by the event.

Viewing Webhook Activity

1. Click on Tools

2. Under the heading Tools and Utilities click on Webhook Activity

3. A table will display activity on the Webhook Activity page