Webhooks <5.5Preview>

NOTE Webhooks is a Sentinel EMS add-on feature available with an active webhooks subscription plan.

>What Is a Webhook?

>What Is an Event?

>Webhook Status

>Prerequisites for Creating a Webhook

>Creating a Webhook

>Actions for Webhooks

>About Authentication Profiles
See Authentication Profiles <5.5Preview>

What Is a Webhook?

Webhooks enable Sentinel EMS to notify client applications (or services) about a change or an update to a Sentinel EMS entity. Sentinel EMS uses webhooks to send event notifications to the client applications enabling the application to take an action in response to the event, for example:

>Synchronizing data between two applications

>Triggering automated workflows

>Allowing third-party integrations

In Sentinel EMS, webhooks support OAuth and Basic authentication to send HTTP requests to the client applications.

What Is an Event?

An event is created whenever an operation is performed on a Sentinel EMS entity, such as namespace or product. A webhook creates a subscription to the required event. For example, if you subscribe to the Contact Added event, you will receive the detailed information (JSON payload) every time a contact is added in Sentinel EMS.

You can create webhook subscriptions for the following events:

Entity	Event
Namespace	>Namespace Added >Namespace Updated
Feature	>Feature Added >Feature Updated
Product	>Product Added >Product Updated
Product Suite	>Product Suite Added >Product Suite Updated
License Model	>License Model Added >License Model Updated
Customer	>Customer Added >Customer Updated
Contact	>Contact Added >Contact Updated
Entitlement	>Entitlement Added >Entitlement Updated
Fingerprint	>Fingerprint Added >Fingerprint Updated
Custom Attribute	>Custom Attribute Added >Custom Attribute Updated
List Attribute	>List Attribute Added >List Attribute Updated
Activation	>Activation Added >Activation Updated
Product Key	>Product Key Quantity Exhausted

Event Data

A webhook subscribes to a Sentinel EMS event. When the subscribed event occurs in Sentinel EMS, the webhook delivers its data in JSON format to the configured URL in an HTTP POST request.

The following sample shows an example of the event data that a webhook delivers to the client application URL:

{
    "eventName": "Namespace Added",
    "entityName": "Namespace",
    "webhookId": "3d3d4461-8ff7-4831-9654",
    "webhookName": "TestWebhook",
    "activityName": "Add Namespace",
    "requestId": "3f59dfdb-3b65-4187-a44c-05ebaf1bf726",
    "eventId": "33c572c7-c05e-4215-a8d4",
    "url": "https://www.example.com/ems/api/v5/namespaces",
    "entityId": "735e1160-0b2d-47bc-afc6",
    "currentState": "{\"namespace\":{\"id\":\"735e1160-0b2d-47bc-afc6-0fea5e7cbac1\",\"creationDate\":\"2022-12-29 15:50\",\"lastModifiedDate\":\"\",\"name\":\"need_value\",\"description\":\"\",\"state\":\"DRAFT\",\"refId1\":\"\",\"refId2\":\"\"}}",
    "previousState":"{\"namespace\":{\"id\":\"735e1160-0b2d-47bc-afc6-0fea5e7cbac1\",\"creationDate\":\"2022-12-29 15:50\",\"lastModifiedDate\":\"\",\"name\":\"need_value\",\"description\":\"\",\"state\":\"DRAFT\",\"refId1\":\"\",\"refId2\":\"\"}}"
}

The parameters included in the event data are:

>eventName: Name of the subscribed event.

>entityName: Name of the Sentinel EMS entity for which the event occurred.

>webhookId: Unique identifier of the webhook.

>webhookName: Name of the webhook.

>activityName: Name of the activity that causes the event. For example, "Add Feature" and "Bulk Feature Upload" activities result in the "Feature Added" event.

>requestId: Unique identifier of the HTTP request sent to Sentinel EMS and from Sentinel EMS to client applications.

>eventId: Identifier of the subscribed event in Sentinel EMS.

>url: URL of the Sentinel EMS endpoint that is called for the event to happen.

>entityId: Identifier of the Sentinel EMS entity for which the event occurred.

>currentState: State (JSON) of the entity after the event occurred.

>previousState: State (JSON) of the entity before the event occurred.

NOTE The current state and previous state are included in the event data only if Include Data is set to Yes in a webhook.

Built-in Retries for Webhooks

A webhook may fail to deliver data for a number of reasons, such as authorization failure or server is not reachable. Sentinel EMS webhooks attempt to deliver the event data to the client URL for a predefined number of times. After that, the webhook delivery is marked as failed. Use Sentinel EMS REST API to get details of events for which webhook delivery failed.

Webhook Status

By default, a webhook is enabled. You can disable a webhook if you want it to stop sending the event data to the client application.

Prerequisites for Creating a Webhook

Only Sentinel EMS administrators can create webhooks. An authentication profile (Basic or OAuth) is required by webhooks to authenticate to the client applications. You can also define an authentication profile when creating a webhook.

Creating a Webhook

To create a webhook:

1.From the navigation pane, select Configuration > Webhooks to view the Webhooks page.

2. Click Add Webhook. The Add Webhook page opens.

3.Fill in the webhook attributes (described in the next section), and click Save.

Webhook Attributes

The following table explains the attributes that are used to create a webhook:

Attribute	Description	Required/Optional	Valid Values
Event	Name of the event subscribed by the webhook.	Required	>A list of predefined events
Name	Unique name of the webhook.	Required	>Alphanumeric >Special characters >Up to 100 characters
Endpoint URL	The URL of the client application to which the webhook posts the event data in the form of JSON.	Required	>Alphanumeric >Up to 2000 characters
Authentication Profile	Name of the authentication profile associated with the webhook. Enter a space to view the list of available authentication profiles. Select an authentication profile from the displayed list or click the Add Authentication button to create a new one. For details, see Creating an Authentication Profile.	Required	A new or an existing authentication profile
Description	A friendly description to identify the webhook.	Optional	>Alphanumeric >Up to 500 characters
Include Data	Specifies whether to include previous and current states of the entity (for which the event happened) in the event data sent to the endpoint URL.	Optional	Yes OR No Default: Yes
Enable Webhook	Determines whether the webhook can post event data to the endpoint URL.	Optional	Yes OR No Default: Yes

Actions for Webhooks

The following table lists the actions available for webhooks:

Action

Description

Edit

Updates an existing webhook.

See Editing an Entity to understand how to edit an entity.

Disable

Prevents the webhook from sending the event data to the client application.

Delete

Deletes a webhook.