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