Publicar eventos do Microsoft Dataverse com webhooks
Outro método para publicar eventos do Microsoft Dataverse em um serviço externo é registrar webhooks. Um webhook é um mecanismo com base em HTTP para publicar eventos em qualquer serviço com base em API Web que você escolher. Esse método permite escrever código personalizado hospedado em serviços externos como uma integração ponto a ponto.
Webhooks x Barramento de Serviço do Azure
Ao considerar mecanismos de integração, você tem algumas opções disponíveis. É importante que você considere vários elementos ao escolher um determinado método.
Considere usar o Barramento de Serviço do Azure quando:
O processamento/enfileiramento assíncrono de alta escala for um requisito.
Vários assinantes puderem precisar consumir determinado evento do Dataverse.
Você quiser governar sua arquitetura de integração em um local centralizado.
Considere usar webhooks quando:
O processamento síncrono em um sistema externo for necessário como parte de seu processo (o Dataverse só dá suporte ao processamento assíncrono em pontos de extremidade do Barramento de Serviço).
A operação externa que você está executando precisar ocorrer imediatamente.
Você desejar que toda a transação falhe, a menos que o serviço externo processe com êxito o payload do webhook.
Já existir um ponto de extremidade de API Web de terceiros que você queira usar para integração.
A autenticação de SAS (Assinatura de Acesso Compartilhado) não é preferida ou viável (webhooks dão suporte à autenticação por meio de cabeçalhos de autenticação e chaves de parâmetro de cadeia de consulta).
Opções de autenticação de webhook
A tabela a seguir descreve as três opções de autenticação que podem ser usadas para consumir uma mensagem de webhook de um determinado ponto de extremidade.
| Tipo | Descrição |
|---|---|
| HttpHeader | Inclui um ou mais pares de chave e valor no cabeçalho da solicitação HTTP. Exemplo: Key1: Value1, Key2: Value2 |
| WebhookKey | Inclui uma cadeia de consulta usando o código como a chave e um valor que é exigido pelo ponto de extremidade. Ao registrar o webhook usando a Plug-in Registration Tool, insira somente o valor. Exemplo: ?code=00000000-0000-0000-0000-000000000001 |
| HttpQueryString | Inclui um ou mais pares de chave e valor como parâmetros de cadeia de consulta. Exemplo: ?Key1=Value1&Key2=Value2 |
Cabeçalhos HTTP de webhook
A tabela a seguir mostra os cabeçalhos HTTP que são transmitidos ao seu serviço como parte de uma chamada a webhook. Você poderá usar estes cabeçalhos como parte do método de processamento se estiver escrevendo um novo processador de webhook.
| Chave | Descrição do valor |
|---|---|
| x-request-id | Um identificador exclusivo para a solicitação |
| x-ms-dynamics-organization | O nome do locatário que enviou a solicitação |
| x-ms-dynamics-entity-name | O nome lógico da entidade que transmitiu os dados de contexto da execução |
| x-ms-dynamics-request-name | O nome do evento para o qual a etapa do webhook foi registrada |
| x-ms-correlation-request-id | Identificador exclusivo para rastrear qualquer tipo de extensão. Essa propriedade é usada pela plataforma para prevenção de loop infinito. Na maioria dos casos, essa propriedade pode ser ignorada. Esse valor poderá ser usado quando você estiver trabalhando com o suporte técnico, pois ele pode ser usado para consultar a telemetria a fim de entender o que ocorreu durante toda a operação. |
| x-ms-dynamics-msg-size-exceeded | Enviado somente quando o tamanho do conteúdo HTTP exceder 256 KB |
Registrar um ponto de extremidade de webhook
O registro de ponto de extremidade de webhook é realizado de forma semelhante ao registro de ponto de extremidade de serviço, usando a Plug-in Registration Tool.
Na Plug-in Registration Tool, você pode registrar um novo webhook selecionando Registrar Novo Webhook na opção de menu Registrar.
Será exibida a caixa de diálogo Registro de Webhook, em que você poderá configurar a URL do ponto de extremidade com as opções de autenticação.
Registrar com autenticação HTTPHeader
Se a autenticação HttpHeader for selecionada, a tela solicitará que você adicione Chaves e Valores que serão transmitidos como parte da solicitação HTTP. Normalmente, as chaves e os valores podem incluir um token de portador do OAuth ou vários outros formatos de autenticação.
Registrar com autenticação WebhookKey
Se WebhookKey for especificado como o método de Autenticação, uma cadeia de consulta será transmitida para a URL com a chave fornecida no formato ?code=[web hook key]. Esse método é útil quando você chama o Azure Functions, pois ele usa esse parâmetro de código por padrão para realizar sua autenticação.
Registrar com autenticação HTTPQueryString
Você pode transmitir parâmetros de cadeia de consulta especificando HttpQueryString como a opção de Autenticação. Assim como a opção HTTPHeader, ela apresenta a opção de transmitir um conjunto de pares de chave/valor para a sua API Web. Você também pode passar outros parâmetros e até mesmo passar manualmente o parâmetro "código" esperado por meio do Azure Functions dessa maneira.
