Forrige

Neste

Publish Microsoft Dataverse events with webhooks

Completed

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.

Type	Description
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.

Key	Value Description
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.

Continue