CloudEvents - Webhook Notification Service

Title CloudEvents
Type Service


  • Webhooks
  • Messaging

Webhook Notifications based on CloudEvents specification

The CloudEvents service implements the CloudEvents specification for emitting webhooks to subscribers. Webhooks subscribe to one or more event types and applications emit an event for exactly one of those events. A subscribtion can be further detailed by filtering to a subject (or topic). In that case a subscriber only receives an event if a) it has subscribed to the event type and b) the event subject starts with the subject filter of the subscriber.
Besides some common metadata, events include a payload. Although there is no limit on the size of the payload, event payloads should be lightweight and should only contain the necessary data the webhook subscriber needs for further processing. You pass event payloads as serialized JSON and the service deserializes that to a JSON object.
An important note. Processing events - meaning sending an event to webhooks - is done by Light BPT. There is a limit of 20 running Light BPT processes by frontend server. So if you have two frontend server 40 processes can run at the same time - over all your applications. If you use Light BPT in other applications you might have less than 40 slots for processing webhook events. Long story short that doesn't scale well. So if you are planning to notify a large number of webhooks or if you have the need of time critial delivery of webhook events you should integrate with notification service like Azure Event Grid. The good thing is, that you can start using this CloudEvents service and later "step up" to Azure Event Grid as both are using the CloudEvents specification.
Getting started

Install the Demo application to give it a first try and get to know the basic setup to register webhooks and trigger events.

In order to emit events to webhooks you need to

  • Register a webhook with at least one event type
  • (optional) Perform endpoint / webhook validation
  • Send events to event type

To test webhooks you can use This tool gives you a webhook url you can use to register a webhook with the CloudEvents service and monitor received events.

Use either the WebhookRegister server action or the CloudEvents_WebhookRegister service action to register a new webhook by its url and one or more event types. Optionally you can required the endpoint (the target url) to validate before it can receive events.

The CloudEvents specification requires, that the endpoint validates the subscription. If you enable Require Validation, the endpoint url immediatly receives a http OPTIONS request with an origin and a callback url. The callback url consists of the subscriber id (generated by the CloudEvents service upon registration) and a validation code. The endpoint must do a GET request to the callbackurl within 5 minutes. If validation succeeded then the webhook is set to active and can receive events. If it does not respond within 5 minutes, the registration is automatically deleted.

After registration (and optional validation) use EventPush server action or CloudEvents_EventPush service action to trigger event notification for an event type.

Validation REST endpoint

The CloudEvents module exposes a single REST endpoint Validate. This one is responsible for validating endpoints - in case you registered a webhook with RequireValidation set to true. The full url to this endpoint is constructed of the default DNS domain name of your environment. (The parameters table is queried for that to retrieve it).

Purge Timer

The CloudEvents module has a timer which purges event data along with queue entries that are 7 days or older. You have to manually specify a schedule if you want it to run automatically.

All Server Actions

EventGet - Get details of a single event

EventPush - Triggers webhook notification by emitting an event to a event type (and optional subject). Data must be given as serialized JSON. Use JSONSerialize along with a Structure to create the data payload for the event.

QueueGet - For every notification - combination of event and subscriber - a queue entry is created. Use this action retrieve details for a specific queue entry.

SubscriberGet - Get details for a specific subscriber by subscriber identifier.

SubscriberDelete - Delete a subscriber by subriber identifier

WebhookGet - Get details for a specific webhook subscriber by its registration url.

WebhookDelete - Delete a webhook subscriber by its registration url.

WebhookRegister - Register (add) a new webhook subscriber. Please note that a registration url must be unique across all subscriptions.

Each server action has a corresponding service action wrapper prefixe by CloudEvents_ Use service action for loose coupling with your applications. (recommended).



Why is there no REST endpoint for webhook registration ?

The service only exposes a validation endpoint but not a registration endpoint. When registering a new webhook via an API you must ensure that the webhook authenticates with your API. Authentication is completely up to you. Use API Keys, Basic Authentication or a more sophisticated authentication mechanism like OAUTH or JWT Bearer Tokens. As there is no default way on how to authenticate we decided to not include a registration endpoint into the service.

How is the full url created for the validation callback url ?

The full url to the validation endpoint is created "https://" + DefaultDNSName + "/CloudEvents/rest/Webhook/Validate/" + SubscriberId + "?Code=" + ValidationCode

DefaultDNSName is retrieved by querying the Parameter entity (System) to get the default DNS name of the current environment.

SubscriberId is the unique identifier of a registered webhook - a GUID.

ValidationCode is a created alphanumeric password with 32 characters upon subscriber creation.


You are using an outdated browser. The website may not be displayed correctly. Close