Event handler in Azure Web PubSub service

Article
01/31/2023

The event handler handles the incoming client events. Event handlers are registered and configured in the service through the Azure portal or Azure CLI. When a client event is triggered, the service can send the event to the appropriate event handler. The Web PubSub service now supports the event handler as the server-side, which exposes the publicly accessible endpoint for the service to invoke when the event is triggered. In other words, it acts as a webhook.

The Web PubSub service delivers client events to the upstream webhook using the CloudEvents HTTP protocol.

For every event, the service formulates an HTTP POST request to the registered upstream endpoint and expects an HTTP response.

The data sending from the service to the server is always in CloudEvents binary format.

Screenshot of Web PubSub service event trigger.

Upstream and Validation

When you configure the webhook endpoint, the URL can include the {event} parameter to define a URL template. The service calculates the value of the webhook URL dynamically when the client request comes in. For example, when a request /client/hubs/chat comes in, with a configured event handler URL pattern http://host.com/api/{event} for hub chat, when the client connects, it will first POST to this URL: http://host.com/api/connect. The {event} parameter can be useful when a PubSub WebSocket client sends custom events, that the event handler helps dispatch different events to different upstream endpoints. The {event} parameter isn't allowed in the URL domain name.

When setting up the event handler webhook through Azure portal or CLI, the service follows the CloudEvents Abuse Protection to validate the upstream webhook. Every registered upstream webhook URL will be validated by this mechanism. The WebHook-Request-Origin request header is set to the service domain name xxx.webpubsub.azure.com, and it expects the response to have a header WebHook-Allowed-Origin to contain this domain name or *.

When doing the validation, the {event} parameter is resolved to validate. For example, when trying to set the URL to http://host.com/api/{event}, the service will try to OPTIONS a request to http://host.com/api/validate. And only when the response is valid, the configuration can be set successfully.

For now, we don't support WebHook-Request-Rate and WebHook-Request-Callback.

Authentication between service and webhook

You can use any of these methods to authenticate between the service and webhook.

Anonymous mode
Simple authentication with ?code=<code> is provided through the configured Webhook URL as query parameter.
Microsoft Entra authorization. For more information, see Use a managed identity in client events.

Configure event handler

Configure through Azure portal

You can add an event handler to a new hub or edit an existing hub.

To configure an event handler in a new hub:

Go to your Azure Web PubSub service page in the Azure portal.
Select Settings from the menu.
Select Add to create a hub and configure your server-side webhook URL. Note: To add an event handler to an existing hub, select the hub and select Edit.
Enter your hub name.
Select Add under Configure Even Handlers.
In the event handler page, configure the following fields: 1. Enter the server webhook URL in the URL Template field. 1. Select the System events that you want to subscribe to. 1. Select the User events that you want to subscribe to. 1. Select Authentication method to authenticate upstream requests. 1. Select Confirm.
Select Save at the top of the Configure Hub Settings page.

Configure through Azure CLI

Use the Azure CLI az webpubsub hub group commands to configure the event handler settings.

Commands	Description
`create`	Create hub settings for WebPubSub Service.
`delete`	Delete hub settings for WebPubSub Service.
`list`	List all hub settings for WebPubSub Service.
`show`	Show hub settings for WebPubSub Service.
`update`	Update hub settings for WebPubSub Service.

Here's an example of creating two webhook URLs for hub MyHub of MyWebPubSub resource:

az webpubsub hub create -n "MyWebPubSub" -g "MyResourceGroup" --hub-name "MyHub" --event-handler url-template="http://host.com" user-event-pattern="*" --event-handler url-template="http://host2.com" system-event="connected" system-event="disconnected" auth-type="ManagedIdentity" auth-resource="uri://myUri"