Webhooks

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

Prerequisites for Creating a Webhook

Only Sentinel EMS administrators can create webhooks. Webhooks require an authentication profile (Basic or OAuth) to authenticate with client applications. You can define the authentication profile when creating the webhook.

Events and Activities

This section describes the events and activities supported by Sentinel EMS webhooks.

Events (What Happens)

An event indicates that a change has occurred in a Sentinel EMS entity. It is triggered whenever an operation—such as creating or updating an entity—takes place. For example, when you add a new entitlement, the Entitlement Added event is triggered. You can subscribe to events using webhooks. When a subscribed event occurs, Sentinel EMS sends a notification, along with detailed information (in a JSON payload), to your application.

Activities (How It Happens)

An activity identifies the specific operation that caused the event. While an event indicates that something happened, an activity explains the exact action that triggered it. A single event can be triggered by multiple activities. For example, the Entitlement Added event can result from activities such as Add Entitlement, Split or Transfer Entitlement, or Bulk Entitlement Upload. When configuring a webhook, you can filter event notifications based on these activities so that notifications are sent only for the specific operations you want to track. The webhook payload includes the activity name, allowing your application to determine the exact cause of the event.

The following table lists the supported events by entity and operation, along with their corresponding activities. Here, "Contact" refers to the User entity, and "User" refers to the Vendor User entity:

NOTE   Use the event and activity names exactly as shown in this table when configuring the webhook endpoints in Sentinel EMS REST API Reference. Activity names are case-sensitive and space-sensitive. For example, the Add Entitlement activity is valid, but Add entitlement or AddEntitlement is not.

{
"eventName": "Namespace Added",
"entityName": "Namespace",
"webhookId": "08c61b38-8523-4eb1-9b01-b12a2e6a583c",
"webhookName": "NSADD",
"activityName": "Add Namespace",
"requestId": "9876f57e-58d7-460d-bc39-06d6ee65be1b",
"eventId": "5c9d6072-b5bf-4640-8aae-422a52847994",
"url": "https://api.example.com/ems/v5/namespaces",
"entityId": "e60db72f-a446-43cb-9a25-0d8c36fe7b3b",
"currentState": "{\"namespace\":{\"id\":\"e60db72f-a446-43cb-9a25-0d8c36fe7b3b\",\"createdBy\":\"admin\",\"creationDate\":\"2025-07-23 10:01\",\"lastModifiedBy\":\"\",\"lastModifiedDate\":\"\",\"name\":\"EDUCATIONAL\",\"description\":\"\",\"state\":\"DRAFT\",\"refId1\":\"\",\"refId2\":\"\"}}",
"opDatetime": "2025-07-23 10:01:33.437"
}

{
"eventName": "Namespace Updated",
"entityName": "Namespace",
"webhookId": "9788bfb9-14d3-494c-b583-f27280b3e367",
"webhookName": "NSUPD",
"activityName": "Replace Namespace",
"requestId": "8edffd14-7f60-4f7a-9390-4cb645f5f4d7",
"eventId": "aee827d7-d1e6-4ae8-ab9b-db5791ab3bda",
"url": "https://api.example.com/ems/v5/namespaces/123e4567-e89b-12d3-a456-426614174000",
"entityId": "e60db72f-a446-43cb-9a25-0d8c36fe7b3b",
"previousState": "{\"namespace\":{\"id\":\"e60db72f-a446-43cb-9a25-0d8c36fe7b3b\",\"createdBy\":\"admin\",\"creationDate\":\"2025-07-23 10:01\",\"lastModifiedBy\":\"\",\"lastModifiedDate\":\"\",\"name\":\"EDUCATIONAL\",\"description\":\"\",\"state\":\"DRAFT\",\"refId1\":\"\",\"refId2\":\"\"}}",
"currentState": "{\"namespace\":{\"id\":\"e60db72f-a446-43cb-9a25-0d8c36fe7b3b\",\"createdBy\":\"admin\",\"creationDate\":\"2025-07-23 10:01\",\"lastModifiedBy\":\"admin\",\"lastModifiedDate\":\"2025-07-23 10:02\",\"name\":\"EDUCTATIONAL\",\"description\":\"educational
items\",\"state\":\"DRAFT\",\"refId1\":\"\",\"refId2\":\"\"}}",
"opDatetime": "2025-07-23 10:02:30.409"
}

{
"eventName": "Product Key Quantity Exhausted",
"entityName": "Entitlement",
"webhookId": "320d390f-0360-4149-b69d-bcadcf2ce8b3",
"webhookName": "PKIDQTYEXHT",
"activityName": "Add Activation",
"requestId": "d8f9df9d-4d86-4d92-a71c-e6b396834eb7",
"eventId": "e0d78fdb-6b3e-427a-92d1-51b666ddc9ab",
"url": "https://api.example.com/ems/v5/activations/bulkActivate",
"entityId": "9d03e346-82eb-4059-b95e-1b1e205ca07b",
"opDatetime": "2025-07-23 10:04:14.760"
}

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 and click Save.

Webhook Attributes

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

Trigger Conditions

When creating or editing a webhook, you can define trigger conditions. Webhook trigger conditions allow you to define specific conditions that determine when a webhook should be processed. This removes the need for external filtering or dispatcher services by enabling you to configure conditions directly within the webhook definition.

You can use trigger conditions to implement selective event handling, such as filtering events for specific products, customers, partners, or market groups, based on attributes such as product mappings or geographical regions. This ensures that only relevant events trigger the webhook, improving efficiency and reducing unnecessary processing.

To manage trigger conditions:

1.In the Add Webhook page, click the Manage Trigger Conditions button.

2.In the Manage Trigger Conditions dialog box, define the Webhook Trigger Conditions Attributes and click Save.

Webhook Trigger Conditions Attributes

Managing Trigger Conditions—A Walkthrough

The following expression comprises a nested set of conditions:

((entitlement.customer.name == 'Sam Smith' && entitlement.state == 'ENABLE') || (entitlement.contact.externalId == '617AWUD'))

To create this expression, perform the following steps in the Manage Trigger Conditions dialog box:

1.Click the Delete button to remove the existing condition row.
2.Click Add Filter Group twice to create two filter groups, under which you can define multiple sets of conditions.
3.Click Or in the parent filter group to define the logical relationship between the filter groups.
4.Click Add Condition twice to create two condition rows in the first filter group.
5.Set the following values in the newly added condition rows: 1st Condition Row: •Attribute: Customer Name •Operator: Is equal to •Value: Sam Smith 2nd Condition Row: •Attribute: Entitlement State •Operator: Is equal to •Value: ENABLE
6.Click Add Condition to add a new condition row in the second filter group.
7.Set the following values in the newly added condition row: •Attribute: User ExternalId •Operator: Is equal to •Value: 617AWUD
8.Click Save.

Defining Trigger Conditions Using the Sentinel EMS REST API

You can use the Add Webhook, Replace Webhook, and Update Webhook APIs, as described in the Sentinel EMS REST API Reference, to define trigger conditions. These APIs offer greater flexibility by supporting advanced JSON path navigation operators.

For example, when using the API, you can include both the [*] array wildcard to access all items and [index] indexed array to access a specific item. In contrast, trigger conditions created through the Manage Trigger Condition dialog box in Sentinel EMS vendor portal support only the [*] operator. As a result, if a trigger condition is defined through the Sentinel EMS REST API and contains symbols other than [*], it can only be modified using the API, not through the Sentinel EMS vendor portal.

The following symbols are supported using APIs:

Troubleshooting and Retries

When a webhook fails to deliver a notification, Sentinel EMS automatically attempts to resend it. This section explains the retry mechanism and provides guidance on how to troubleshoot and resolve delivery failures.

Retry Mechanism

When a delivery fails, Sentinel EMS automatically retries up to three times at predefined intervals. The interval between retries is not configurable, and the entire retry sequence is completed within approximately one hour.

Notification Delivery States

Webhook notifications can have the following delivery states during the retry process:

>In-progress State: Indicates that automatic retries are in progress. During this time, the notification cannot be manually retried.

>Failed State: Indicates that all automatic retries have failed. You can investigate the cause and manually retry the notification.

Troubleshooting Failed Notifications

Use the following approach to troubleshoot failed webhook notifications:

1.Identify Failed Notifications: Use the Search Events API, as described in the Sentinel EMS REST API Reference, to find event notifications with a "FAILED" delivery status. The response may include an error message that helps diagnose the issue. You can search for notifications by webhook ID, event ID, or a time range.

2.Diagnose the Root Cause: Based on the error message and your configuration, identify the issue. Common problems include:

•Incorrect Endpoint URL: Ensure the URL in the webhook definition is correct and publicly accessible. Sentinel EMS cannot reach `localhost` or other private network addresses.

•Authentication Failures: Verify the credentials configured in the associated Authentication Profile. Check for expired passwords, incorrect client secrets, or invalid token URLs.

•Subscriber Application Errors: Inspect the logs of your endpoint application. It may return an HTTP 4xx or 5xx error, indicating a problem with how it processes the incoming request from Sentinel EMS.

•Network and Firewall Issues: Confirm that your firewall or network security rules are not blocking POST requests from Sentinel EMS IP addresses.

3.Manually Retry the Notification: Once you have fixed the underlying issue, use the Retry Event API, as described in the Sentinel EMS REST API Reference, to request another delivery attempt. You can retry a single notification by its event ID or multiple notifications using filters. This triggers up to three new delivery attempts.

4.Clean Up Failed Notifications (Optional): If the issue has already been resolved or the notifications no longer need to be delivered, you can use the Mark as Bulk Successful API, as described in the Sentinel EMS REST API Reference. This action changes the status of specified failed notifications to successful and removes them from the failure queue, which can help simplify monitoring.

Actions for Webhooks

The following table lists the actions available for webhooks:

Action		Description
	Edit	Updates an existing webhook. For details on editing webhooks, see Editing an Entity.
	Disable	Prevents the webhook from sending event data to the subscriber application.
	Delete	Deletes a webhook.