Configure event handler in Azure Web PubSub service

Article
09/23/2024

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 configured upstream webhook using the CloudEvents HTTP protocol, with CloudEvents extension for Azure Web PubSub event handler.

Screenshot of Web PubSub service event trigger.

Event handler settings

A client always connects to a hub, and you could configure multiple event handler settings for the hub. The order of the event handler settings matters and the former one has the higher priority. When a client connects and an event is triggered, Web PubSub goes through the configured event handlers in the priority order and the first matching one wins. Set the following properties when you configure the event handler:

Property name	Description
Url template	Defines the template Web PubSub uses to evaluate your upstream webhook URL.
User events	Defines the user events that current event handler setting cares about.
System events	Defines the system events that current event handler setting cares about.
Authentication	Defines the authentication method between the Web PubSub service and your upstream server.

Events

The events include user events and system events. System events are predefined events that are triggered during the lifetime of a client. User events are triggered when the client sends data, the user event name can be customized using client protocols, here contains the detailed explanation.

Event type	Supported values
System events	`connect`, `connected`, and `disconnected`
User events	`message`, or custom event name following client protocols

URL template

URL template supports several parameters that can be evaluated during runtime. With this feature, it's easy to route different hubs or events into different upstream servers with a single setting. KeyVault reference syntax is also support so that data could be stored in Azure Key Vault securely.

Note URL domain name shouldn't contain parameter syntax, for example, http://{hub}.com isn't a valid URL template.

Supported parameters	Syntax	Description	Samples
Hub parameter	`{hub}`	The value is the hub that the client connects to.	When a client connects to `client/hubs/chat`, a URL template `http://host.com/api/{hub}` evaluates to `http://host.com/api/chat` because for this client, hub is `chat`.
Event parameter	`{event}`	The value of the triggered event. `event` values are listed here. The event value for abuse protection requests is `validate` as explained here.	If there's a URL template `http://host.com/api/{hub}/{event}` configured for event `connect`, When a client connects to `client/hubs/chat`, Web PubSub initiates a POST request to the evaluated URL `http://host.com/api/chat/connect` when the client is connecting, since for this client event, hub is `chat` and the event triggering this event handler setting is `connect`.
KeyVault reference parameter	`{@Microsoft.KeyVault(SecretUri=<secretUri>)}`	The SecretUri should be the full data-plane URI of a secret in the vault, optionally including a version, for example, `https://myvault.vault.azure.cn/secrets/mysecret/` or `https://myvault.vault.azure.cn/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`. When using KeyVault reference, you also need to configure the authentication between your Web PubSub service and your KeyVault service, check here for detailed steps.	`@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.cn/secrets/mysecret/)`

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.

Upstream and Validation

When setting up the event handler webhook through Azure portal or CLI, the service follows the CloudEvents Abuse Protection to validate the upstream webhook. This mechanism validates every registered upstream webhook URL. 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 tries 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.

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"