Subscriptions

Use this API to create and manage webhook subscriptions. Subscription information is represented in the webhook subscription object. Use the Get All Resources API to view all available webhook resources and events that are available for subscription.

Webhook Subscriptions

You can register multiple subscriptions for a single resource, but subscriptions cannot overlap in a domain.

Subscription Signing Key

Every subscription has a signing key (previously known as "Webhook secret"). When a webhook notification is received, the signing key serves as a password that maps to the subscription's ID to validate the notification.

A subscription’s signing key is defined by the signingkey attribute in the subscription object at the time the subscription is created. You can either provide a custom value for signingkey or allow the default signing key to be used. If no value is provided for signingkey, the Encompass platform generates a default signing key. The signing key is passed when creating or updating the subscription and is returned when retrieving subscriptions.

Complexity Requirements for Signing Keys
When providing your own signing key, the signing key must:

  • Be a minimum of 32 characters in length
  • Be a maximum of 64 characters in length
  • Contain at least 1 upper case and 1 lowercase character
  • Contain at least 1 alphabetic and 1 numeric character
  • Contain at least 1 of the following special characters: ! @ # $ ^ & *

In addition, the signing key must not contain empty or blank spaces.

Custom Auth for Webhook Notifications

In addition to the signing key to validate the signature upon receipt of the notification, ICE MT also supports Custom Authorization (Custom Auth) for webhook notifications. Custom Auth for webhooks enables customer specified authorization flow before posting webhook notification to the subscribed endpoint.

See the Custom Authorization page for details.