Webhooks

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

>What Is a Webhook?

>Prerequisites for Creating a Webhook

> What Is an Event?

>Webhook Status

>Creating a Webhook

>Actions for Webhooks

>About Authentication Profiles
See Authentication Profiles

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.

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.

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 Feature Added event, you will receive the detailed information (JSON payload) every time a feature is added in Sentinel EMS.

You can create webhook subscriptions for the following events, where "Contact" refers to the User entity, and "User" refers to the Vendor User entity.

Entity Name	Operation	Activity Name	Event Name
Namespace	Create	Add Namespace	Namespace Added
Namespace	Update	Update Namespace	Namespace Updated
Namespace	Update	Replace Namespace	Namespace Updated
Namespace	Delete	Delete Namespace	Namespace Updated
Feature	Create	Add Feature	Feature Added
Feature	Create	Bulk Feature Upload	Feature Added
Feature	Update	Update Feature	Feature Updated
Feature	Update	Replace Feature	Feature Updated
Feature	Delete	Delete Feature	Feature Updated
Feature	Update	Update License Models	Feature Updated
Feature	Update	Replace License Models	Feature Updated
Feature	Update	Delete License Models	Feature Updated
Product	Create	Add Draft Product	Product Added
Product	Create	Add Product	>Product Added >Namespace Updated
Product	Create	Bulk Product Upload	Product Added
Product	Update	Update Product	Product Updated
Product	Update	Replace Product	Product Updated
Product	Delete	Delete Product	Product Updated
Product	Update	Replace Associated Features	Product Updated
Product	Update	Update Associated Features	Product Updated
Product	Update	Delete Associated Feature	Product Updated
Product Suite	Create	Add Product Suite	Product Suite Added
Product Suite	Create	Bulk Product Suite Upload	Product Suite Added
Product Suite	Update	Update product Suite	Product Suite Updated
Product Suite	Update	Replace Product Suite	Product Suite Updated
Product Suite	Delete	Delete Product Suite	Product Suite Updated
Product Suite	Update	Update Associated Products	Product Suite Updated
Product Suite	Update	Replace Associated Products	Product Suite Updated
Product Suite	Update	Delete Associated Product	Product Suite Updated
License Model	Create	Add License Model	License Model Added
License Model	Update	Update License Model	License Model Updated
License Model	Update	Replace License Model	License Model Updated
License Model	Delete	Delete License Model	License Model Updated
Download	Create	Add Download	Download Added
Download	Update	Update Download	Download Updated
Download	Update	Replace Download	Download Updated
Download	Update	Delete Download	Download Updated
Customer	Create	Add Customer	Customer Added
Customer	Create	Bulk Customer Upload	Customer Added
Customer	Update	Update Customer	Customer Updated
Customer	Update	Replace Customer	Customer Updated
Customer	Delete	Delete Customer	Customer Updated
Customer	Update	Replace Associated Contacts	Customer Updated
Customer	Update	Update Associated Contacts	Customer Updated
Customer	Update	Delete Associated Contact	Customer Updated
Contact	Create	Add Contact	Contact Added
Contact	Create	Bulk Contact Upload	Contact Added
Contact	Update	Update Contact	Contact Updated
Contact	Update	Replace Contact	Contact Updated
Contact	Delete	Delete Contact	Contact Updated
Contact	Create	Register Contact	Contact Updated
Contact	Update	Change Password	Contact Updated
Contact	Update	Forgot Password	Contact Updated
Channel Partner	Create	Add Partner	Partner Added
Channel Partner	Update	Update Partner	Partner Updated
Channel Partner	Update	Replace Partner	Partner Updated
Channel Partner	Update	Delete Partner	Partner Updated
Entitlement	Create	Add Entitlement	>Entitlement Added >Feature Updated >Product Updated
Entitlement	Create	Add Draft Entitlement	Entitlement Added
Entitlement	Create	Add Entitlement	Entitlement Added
Entitlement	Create	Bulk Entitlement Upload	Entitlement Added
Entitlement	Create	Add Batch Entitlement	Entitlement Added
Entitlement	Update	Update Entitlement	Entitlement Updated
Entitlement	Update	Replace Entitlement	Entitlement Updated
Entitlement	Delete	Delete Entitlement	Entitlement Updated
Entitlement	Update	Associate Contact	Entitlement Updated
Entitlement	Update	Remove Associated Contact	Entitlement Updated
Entitlement	Update	Associate Customer	Entitlement Updated
Entitlement	Update	Remove Associated Customer	Entitlement Updated
Entitlement	Update	Add Product Key	Entitlement Updated
Entitlement	Update	Update Product Key	Entitlement Updated
Entitlement	Update	Associate Named Users	Entitlement Updated
Entitlement	Update	Update Associated Named User	Entitlement Updated
Entitlement	Update	Remove Associated Named User	Entitlement Updated
Entitlement	Update	Entitlement Expired	Entitlement Updated
Entitlement	Update	Associate Partners	Entitlement Updated
Entitlement	Update	Remove Associated Partner	Entitlement Updated
Entitlement	Update	Update Associated Partners	Entitlement Updated
Entitlement	Update	Split or Transfer	Entitlement Updated
Entitlement	Create	Split or Transfer	Entitlement Added
Entitlement	Update	Split or Transfer	Product Key Quantity Exhausted
Entitlement	Update	Update Product Key Association	Entitlement Updated
Entitlement	Update	Remove From Product Key	Entitlement Updated
Entitlement	Update	Update Variant Association	Entitlement Updated
Entitlement	Update	Remove From Variant	Entitlement Updated
Entitlement	Update	Update Entitlement Association	Entitlement Updated
Entitlement	Update	Remove From Entitlement	Entitlement Updated
Entitlement	Update	Expired	>Entitlement Expired >Product Key Expired
Fingerprint	Create	Add Fingerprint	Fingerprint Added
Fingerprint	Update	Update Fingerprint	Fingerprint Updated
Fingerprint	Delete	Delete Fingerprint	Fingerprint Updated
Fingerprint	Update	Replace Fingerprint	Fingerprint Updated
Custom Attribute	Create	Add Custom Attribute	>Custom Attribute Added >List Attribute Added
Custom Attribute	Update	Update Custom Attribute	Custom Attribute Updated
Custom Attribute	Delete	Delete Custom Attribute	Custom Attribute Updated
Custom Attribute	Update	Replace Associated Options	List Attribute Updated
Custom Attribute	Update	Update Associated Options	List Attribute Updated
Custom Attribute	Update	Delete Associated Options	List Attribute Updated
Activation	Create	Add Activation	>Activation Added >Product Key Quantity Exhausted
Activation	Create	Renew Activation	Activation Added
Activation	Update	Renew Activation	Activation Updated
Activation	Update	Update Activation	Activation Updated
Activation	Update	Replace Activation	Activation Updated
Activation	Update	Rehost Activation	Activation Added
Activation	Create	Rehost Activation	Activation Updated
Activation	Update	Update Activatees	Activation Updated
Activation	Update	Replace Activatees	Activation Updated
Activation	Update	Mark as Revoked	Activation Updated
Activation	Update	Custom Revocation	Activation Updated
Activation	Update	Generate Permission Tickets	Activation Updated
Activation	Update	Submit Revocation Proofs	Activation Updated
Activation	Update	Confirm Revocation	Activation Updated
Activation	Update	Reject Revocation	Activation Updated
Activation	Update	Mark as Bulk Revoked	Activation Updated
Activation	Update	Manage Activatee	Activation Updated
User	Create	Add User	User Added
User	Update	Update User	User Updated
User	Update	Replace User	User Updated
User	Update	Delete User	User Updated
Role	Create	Add Role	Role Added
Role	Update	Replace Role	Role Updated
Role	Update	Update Role	Role Updated
Role	Update	Delete Role	Role Updated
Application Properties	Update	Update Application Properties	Application Properties Updated
Device	Create	Add Device	Device Added
Device	Update	Update Device	Device Updated
Device	Update	Replace Device	Device Updated
Device	Update	Claim Device	Device Updated
Market Group	Create	Add Market Group	Market Group Added
Market Group	Update	Delete Market Group	Market Group Updated
Market Group	Update	Update Market Group	Market Group Updated
Market Group	Update	Replace Market Group	Market Group Updated
Custom Entity Record	Create	Add Custom Entity Record	Custom Entity Record Added
Custom Entity Record	Update	Replace Custom Entity Record	Custom Entity Record Updated
Custom Entity Record	Update	Update Custom Entity Record	Custom Entity Record Updated
Custom Entity Record	Update	Delete Custom Entity Record	Custom Entity Record Updated
Custom Entity	Create	Add Custom Entity	Custom Entity Added
Custom Entity	Update	Replace Custom Entity	Custom Entity Updated
Custom Entity	Update	Update Custom Entity	Custom Entity Updated
Custom Entity	Update	Delete Custom Entity	Custom Entity Updated
Custom Entity Attribute	Create	Add Custom Entity Attribute	Custom Entity Attribute Added
Custom Entity Attribute	Update	Update Custom Entity Attribute	Custom Entity Attribute Updated
Custom Entity Attribute	Update	Replace Custom Entity Attribute	Custom Entity Attribute Updated
Custom Entity Attribute	Update	Delete Custom Entity Attribute	Custom Entity Attribute Updated
Provisioning Plan	Create	Add Provisioning Plan	Provisioning Plan Added
Provisioning Plan	Update	Update Provisioning Plan	Provisioning Plan Updated
Provisioning Plan	Delete	Delete Provisioning Plan	Provisioning Plan Updated
Provisioning Method	Create	Add Provisioning Method	Provisioning Method Added
Provisioning Method	Update	Update Provisioning Method	Provisioning Method Updated
Provisioning Method	Delete	Delete Provisioning Method	Provisioning Method Updated
Provisioning Association	Create	Add Provisioning Association	Provisioning Association Added
Provisioning Association	Update	Update Provisioning Association	Provisioning Association Updated
Provisioning Association	Delete	Delete Provisioning Association	Provisioning Association Updated
Provisioning Request	Update	Provisioning Request Dispatch	Provisioning Request Sent
Provisioning Request	Update	Update Provisioning Request Status	Provisioning Failed
Provisioning Request	Update	Update Provisioning Request Status	Provisioning Completed
Provisioning Request	Update	Provisioning Request Dispatch	Provisioning Request Dispatch Failed

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 are a few samples showing examples of the event data that webhooks deliver to the client application URL.

Example for the "Add Namespace" Event:

{
"eventName": "Namespace Added",
"entityName": "Namespace",
"webhookId": "875e3d87-e8b6-4556-98f6-612982d90600",
"webhookName": "SampleNamespaceAdd",
"activityName": "Add Namespace",
"requestId": "631b7add-6100-4f2d-a357-85852346ca81",
"eventId": "77b05f9e-32ff-41c2-b6be-243250b7bbb3",
"url": "https://example.com/ems/api/v5/namespaces",
"entityId": "17f1643b-f573-4c05-8039-eccbf62b2088",
"currentState": "{\"namespace\":{\"id\":\"17f1643b-f573-4c05-8039-eccbf62b2088\",\"creationDate\":\"2023-01-24 06:29\",\"lastModifiedDate\":\"\",\"name\":\"Test\",\"description\":\"\",\"state\":\"DRAFT\",\"refId1\":\"\",\"refId2\":\"\"}}",
"httpMethod": "POST",
"performedBy": "admin",
"actualUser": "admin",
"tenantId": "10141c8b-2252-4ad7-9bd3-8b5fdcb59fc7",
"creationDateTime": "2024-01-24 06:29",
"operation": "Create",
"opDatetime": "2024-01-24 06:29:44.000"
}

Example for the "Update Namespace" Event:

{
    "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\":\"2024-12-29 15:50\",\"lastModifiedDate\":\"\",\"name\":\"Name1\",\"description\":\"\",\"state\":\"DRAFT\",\"refId1\":\"\",\"refId2\":\"\"}}",
    "previousState":"{\"namespace\":{\"id\":\"735e1160-0b2d-47bc-afc6-0fea5e7cbac1\",\"creationDate\":\"2024-12-29 15:50\",\"lastModifiedDate\":\"2023-01-24 06:53\",\"name\":\"Name2\",\"description\":\"\",\"state\":\"DRAFT\",\"refId1\":\"\",\"refId2\":\"\"}}"
}

Example for the "Product Key Quantity Exhausted" Event:

{{
"eventName": "Product Key Quantity Exhausted",
"entityName": "Entitlement",
"webhookId": "ef1b571b-a82f-4350-aa74-8aaf0d2524e3",
"webhookName": "productkey",
"activityName": "Add Activation",
"requestId": "66793a69-2e31-4d12-931b-030fd60ff9e2",
"eventId": "17cd72f6-183d-4400-9f40-f118eaa3c912",
"url": "https://example.com/ems/api/v5/activations/bulkActivate",
"entityId": "2394ce00-20de-4fd0-8112-717893990b27",
"currentState": "{
  "entitlement": {
    "externalId": "",
    "createdBy": "admin",
    "creationDate": "2023-11-17 11:29",
    "lastModifiedBy": "admin",
    "lastModifiedDate": "2023-11-17 11:29",
    "entitlementAsWhole": false,
    "eId": "52d00b55-b57b-486c-9565-261d8596972a",
    "id": "1b240166-59ed-4710-acf1-a24e9a58f3b3",
    "startDate": "2023-11-17",
    "expiry": {
      "neverExpires": true
    },
    "customer": {
      "id": "4aa21bca-c832-4e12-a250-5b936669e1dd",
      "name": "TEST112",
      "identifier": "TEST112",
      "externalId": ""
    },
    "contact": null,
    "entitlementPartners": null,
    "userRegistration": "OPTIONAL",
    "refId1": "",
    "refId2": "",
    "activationAllowed": true,
    "allowActivationBy": "ALL_USERS",
    "revocationAllowed": true,
    "state": "ENABLE",
    "sendNotification": true,
    "ccEmail": "",
    "isTest": false,
    "marketGroup": {
      "id": "8d042002-84f9-11ee-8f05-42010a520087",
      "name": "Default"
    },
    "customAttributes": null,
    "productKeys": {
      "productKey": [
        {
          "pkId": "831e39b6-fa66-4208-9718-417a529d5803",
          "creationDate": "2023-11-17 11:29",
          "lastModifiedDate": "2023-11-17 11:29",
          "externalId": null,
          "startDate": "2023-11-17",
          "expiry": {
            "neverExpires": true
          },
          "id": "2394ce00-20de-4fd0-8112-717893990b27",
          "enforcement": {
            "id": "8aced5c3-84f9-11ee-8f05-42010a520087",
            "name": "Sentinel RMS",
            "version": "10.2"
          },
          "totalQuantity": 1,
          "availableQuantity": 1,
          "splittedQuantity": 0,
          "activationMethod": "FIXED",
          "fixedQuantity": 1,
          "state": "ENABLE",
          "item": {
            "itemProduct": {
              "product": {
                "externalId": "",
                "id": "67058d72-9521-4172-8231-73a7ddf0f17e",
                "identifier": "2",
                "productType": "DEFAULT",
                "nameVersion": {
                  "name": "Copy1",
                  "version": "1"
                }
              }
            }
          },
          "customAttributes": null
        }
      ]
    }
  }
}",
"httpMethod": "POST",
"performedBy": "admin",
"actualUser": "admin",
"tenantId": "1a35a0ea-6584-44ad-8a42-2ef329cdacfe",
"creationDateTime": "2023-11-17 11:30",
"operation": "Update",
"opDatetime": "2023-11-17 11:30:05.000"
}

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. It is blank for "Delete" events.

>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.

>The Entitlement Expired event contains full entitlement payload only in the current state.

>The payload of the Product Key Quantity Exhausted event does not contain all the product keys for an entitlement. It contains selective entitlement fields for entitlement, customer, contact (representing the user entity), channel partner, product keys, and custom attributes, without any feature details.

>When an individual product key expires, then the Product Key Expired event is sent. When an entitlement expires, all the product keys in the entitlement also expire, however, only the Entitlement Expired event is sent.

>To configure the time zone in which the Entitlement Expired and Product Key Expired events occur, set the Time Zone for Expiration Events admin console property.

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 three times (this number is non-configurable). 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.

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. For details on editing webhooks, see Editing an Entity.
	Disable	Prevents the webhook from sending event data to the client application.
	Delete	Deletes a webhook.