Publish Microsoft Dataverse events with webhooks
Another method for publishing events from Microsoft Dataverse to an external service is to register webhooks. A webhook is an HTTP-based mechanism for publishing events to any Web API-based service of your choosing. This method allows you to write your own custom code that is hosted on external services as a point-to-point.
Webhooks vs. Azure Service Bus
When considering integration mechanisms, you have a few available options. It's important that you consider various elements when choosing a given method.
Consider using Azure Service Bus when:
High scale asynchronous processing/queueing is a requirement.
Multiple subscribers might be needed to consume a given Dataverse event.
You want to govern your integration architecture in a centralized location.
Consider using webhooks when:
Synchronous processing against an external system is required as part of your process (Dataverse only supports asynchronous processing against Service Bus Endpoints).
The external operation that you are performing needs to occur immediately.
You want the entire transaction to fail unless the webhook payload is successfully processed by the external service.
A third-party Web API endpoint already exists that you want to use for integration purposes.
SAS authentication isn't preferred and/or feasible (webhooks support authentication through authentication headers and query string parameter keys).
Webhook authentication options
The following table describes the three authentication options that you can use to consume a webhook message from a given endpoint.
|HttpHeader||Includes one or more key value pairs in the header of the HTTP request. Example: Key1: Value1, Key2: Value2|
|WebhookKey||Includes a query string by using code as the key and a value that is required by the endpoint. When registering the webhook by using the Plug-in Registration Tool, only enter the value. Example: ?code=00000000-0000-0000-0000-000000000001|
|HttpQueryString||Includes one or more key value pairs as query string parameters. Example: ?Key1=Value1&Key2=Value2|
Webhook HTTP headers
The following table shows the HTTP headers that are passed to your service as part of a webhook call. You can use these headers as part of your processing method if you are writing a new webhook processor.
|x-request-id||A unique identifier for the request|
|x-ms-dynamics-organization||The name of the tenant who sent the request|
|x-ms-dynamics-entity-name||The logical name of the entity that passed in the execution context data|
|x-ms-dynamics-request-name||The name of the event that the webhook step was registered for|
|x-ms-correlation-request-id||Unique identifier for tracking any type of extension. This property is used by the platform for infinite loop prevention. In most cases, this property can be ignored. This value can be used when you are working with technical support because it can be used to query telemetry to understand what occurred during the entire operation.|
|x-ms-dynamics-msg-size-exceeded||Sent only when the HTTP payload size exceeds the 256KB|
Register a Webhook endpoint
Webhook endpoint registration is performed similarly to Service Endpoint registration, by using the Plug-in Registration Tool.
Within the Plug-in Registration Tool, you can register a new webhook by selecting Register New Web Hook under the Register menu option.
The following WebHook Registration dialog box will appear, where you can configure the URL of your endpoint, along with any authentication options.
Register with HTTPHeader Authentication
If HttpHeader authentication is selected, the screen will prompt you to add Keys and Values that will be passed as part of your HTTP request. Commonly, the keys and values might include an OAuth bearer token or other various authentication formats.
Register with WebhookKey Authentication
If WebhookKey is specified as the Authentication method, a query string is passed to the URL with the
given key in the format
?code=[web hook key]. This method is handy when you are
calling Azure Functions because it uses this code parameter by default to perform its authentication.
Register with HTTPQueryString Authentication
You can pass Query String parameters by specifying HttpQueryString as the Authentication option. As with the HTTPHeader option, it presents the option to pass a set of key/value pairs to your Web API. You could also pass additional parameters, and even manually pass the "code" parameter that is expected through Azure Functions in this manner.