Publicar eventos de Microsoft Dataverse con webhooks
Otro método para publicar eventos de Microsoft Dataverse en un servicio externo es registrar webhooks. Un webhook es un mecanismo basado en HTTP para publicar eventos en cualquier servicio de su elección basado en la API web. Este método permite escribir código personalizado hospedado en servicios externos como integración integral.
Webhooks y Azure Service Bus
Al considerar los mecanismos de integración, tiene algunas opciones disponibles. Es importante que tenga en cuenta varios elementos al elegir un método dado.
Considere el uso de Azure Service Bus cuando:
El procesamiento o las colas asincrónicos a gran escala sean un requisito.
Sea posible que se necesiten varios suscriptores para consumir un determinado evento de Dataverse.
Desee gobernar su arquitectura de integración en una ubicación centralizada.
Considere el uso de webhooks cuando:
Se requiera procesamiento sincrónico en un sistema externo como parte del proceso (Dataverse solo admite el procesamiento asincrónico en los puntos de conexión de Service Bus).
La operación externa que está realizando deba ocurrir de inmediato.
Desee que la transacción completa falle a menos que el servicio externo procese con éxito la carga del webhook.
Ya existe un punto de conexión de API web de terceros que desea utilizar para fines de integración.
La autenticación de Firma de acceso compartido (SAS) no es preferida ni factible (los webhooks admiten la autenticación a través de encabezados de autenticación y claves de parámetros de cadena de consulta).
Opciones de autenticación de webhook
La siguiente tabla describe las tres opciones de autenticación que puede usar para consumir un mensaje de webhook desde un punto de conexión determinado.
| Tipo | Descripción |
|---|---|
| HttpHeader | Incluye uno o más pares de valores clave en el encabezado de la solicitud HTTP. Ejemplo: Key1: Value1, Key2: Value2 |
| WebhookKey | Incluye una cadena de consulta mediante el uso de código como clave y un valor requerido por el punto de conexión. Al registrar el webhook mediante Plug-in Registration Tool, solo introduzca el valor. Ejemplo: ?code=00000000-0000-0000-0000-000000000001 |
| HttpQueryString | Incluye uno o más pares de valores clave como parámetros de la cadena de consulta. Ejemplo: ?Key1=Value1&Key2=Value2 |
Encabezados HTTP de Webhook
La siguiente tabla muestra los encabezados HTTP que se pasan al servicio como parte de una llamada de webhook. Puede usar estos encabezados como parte de su método de procesamiento si está escribiendo un procesador de webhook nuevo.
| Clave | Descripción del valor |
|---|---|
| x-request-id | Identificador único de la solicitud |
| x-ms-dynamics-organization | Nombre del suscriptor que envió la solicitud |
| x-ms-dynamics-entity-name | Nombre lógico de la entidad que pasó los datos del contexto de ejecución. |
| x-ms-dynamics-request-name | Nombre del evento para el que se registró el paso de webhook |
| x-ms-correlation-request-id | Identificador único para rastrear cualquier tipo de extensión. La plataforma utiliza esta propiedad para la prevención de bucles infinitos. En la mayoría de los casos, esta propiedad se puede ignorar. Este valor se puede usar cuando se trabaja con el soporte técnico porque se puede usar para consultar la telemetría para comprender lo que ocurrió durante toda la operación. |
| x-ms-dynamics-msg-size-exceeded | Se envía solo cuando el tamaño de la carga HTTP excede los 256 KB |
Registrar un punto de conexión de webhook
El registro del punto de conexión de Webhook se realiza de manera similar al registro de un punto de conexión de servicio, por medio de Plug-in Registration Tool.
En Plug-in Registration Tool, puede registrar un nuevo webhook seleccionando Registrar nuevo webhook en la opción de menú Registrar.
Aparece el siguiente cuadro de diálogo Registro de WebHook, donde puede configurar la URL del punto de conexión, junto con las opciones de autenticación.
Registrarse con la autenticación HTTPHeader
Si se selecciona la autenticación HttpHeader, la pantalla le pedirá que agregue claves y valores que se pasarán como parte de la solicitud HTTP. Comúnmente, las claves y los valores pueden incluir un token de portador de OAuth u otros formatos de autenticación diferentes.
Registrarse con la autenticación WebhookKey
Si se especifica WebhookKey como método de autenticación, se pasa una cadena de consulta a la URL con la clave dada en el formato ?code=[web hook key]. Este método es útil cuando llama a Azure Functions, porque usa este parámetro de código de manera predeterminada para realizar la autenticación.
Registrarse con la autenticación HTTPQueryString
Puede pasar los parámetros de la cadena de consulta especificando HttpQueryString opción de autenticación. Como sucede con la opción HTTPHeader, presenta la opción de pasar un conjunto de pares de clave y valor a la API web. También puede pasar parámetros adicionales e incluso pasar manualmente el parámetro "código" que se espera a través de Azure Functions de esta manera.
