Registrar um webhook

Use a ferramenta de Registro de Plug-in para registrar um webhook. Para obter a ferramenta de Registro de Plug-in, consulte as ferramentas de desenvolvimento do Dataverse.

Na ferramenta Registro de Plug-in, selecione a opção Registrar Novo WebHook .

Ao registrar um webhook, você deve fornecer três itens de informações:

Item	Description
Nome	Um nome exclusivo que descreve o webhook.
URL do ponto de extremidade	A URL na qual postar informações de contexto de execução.
Authentication	Uma das três opções de autenticação. Para qualquer tipo de autenticação, você deve fornecer as chaves que identificam a solicitação como legítima.

Os webhooks registrados dão suporte apenas à porta 80 para HTTP e à porta 443 para HTTPS.

Opções de autenticação

A opção correta de autenticação para registrar o WebHook e os valores a serem usados dependem do que o endpoint espera. O proprietário do ponto de extremidade deve dizer o que usar. Para usar Webhooks com Microsoft Dataverse, o ponto de extremidade deve permitir uma das seguintes opções de autenticação:

Tipo	Description
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 caracteres de consulta usando code como a chave e um valor exigido pelo ponto de extremidade. Ao registrar o WebHook usando a ferramenta Registro de Plug-in, insira apenas 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

Note

A opção WebhookKey é útil com Azure Functions porque a string de consulta usada na autenticação espera um nome de chave como code.

Qualquer solicitação para o ponto de extremidade configurado deve falhar quando as opções de autenticação passadas na solicitação não corresponderem. O endpoint é responsável por essa condição.

Consultar registros do WebHook

Os registros de webhook são armazenados na ServiceEndpoint Table e têm um valor de Contract de 8.

Você pode encontrar detalhes sobre os Webhooks registrados consultando a tabela ServiceEndpoint .

API Web:

GET [organization URI]/api/data/v9.0/serviceendpoints?$filter=contract eq 8&$select= serviceendpointid,name,authtype,url

Mais informações: consultar dados usando a API Web

FetchXml:

<fetch>
  <entity name="serviceendpoint" >
    <attribute name="serviceendpointid" />
    <attribute name="name" />
    <attribute name="authtype" />
    <attribute name="url" />
    <filter>
      <condition attribute="contract" operator="eq" value="8" />
    </filter>
  </entity>
</fetch> 

Mais informações: Usar FetchXml para recuperar dados

Os detalhes sobre os valores de autenticação definidos estão na propriedade AuthValue e não podem ser recuperados.

Registrar uma etapa para Webhook

Registrar uma etapa para um WebHook é como registrar uma etapa para um plug-in. A principal diferença é que você não pode especificar nenhuma informação de configuração.

Assim como um plug-in, você especifica a mensagem e as informações sobre tabelas quando apropriado. Você também pode especificar onde no pipeline de eventos para executar o WebHook, o modo de execução e se deseja excluir qualquer AsyncOperation quando a operação for bem-sucedida.

As informações sobre o Nome da Etapa e a Descrição são preenchidas automaticamente com base nas opções escolhidas, mas você pode alterá-las. Se você não definir alguns Atributos de Filtragem para uma mensagem que dê suporte a eles, será solicitado que você faça isso como práticas recomendadas de desempenho.

Modo de execução e depuração do registro do WebHook

A forma como você registra o WebHook muda sua experiência ao depurar, caso algo não funcione.

Modo assíncrono

Quando você usa o modo de execução assíncrono, o sistema cria um Trabalho do Sistema (asyncoperation) para capturar o êxito ou a falha da operação. Optar por excluir o Trabalho do Sistema quando ele tiver êxito salva o espaço do banco de dados.

O sistema registra todos os erros que ocorrem nas Tarefas do Sistema. No aplicativo da web, você pode acessar Configurações>> para verificar o status de quaisquer webhooks. Há um valor de Motivo do status: Falha. Abra o trabalho do sistema que falhou para encontrar detalhes sobre o motivo da falha.

Consultar trabalhos assíncronos com falha para uma determinada etapa

Quando você souber o sdkmessageprocessingstepid de uma determinada etapa, poderá consultar a Tabela Assíncrona de Operações para quaisquer erros. Você pode usar o valor OwningExtensionId para filtrar os resultados para uma etapa registrada específica. Os exemplos a seguir usam <stepid> para o sdkmessageprocessingstepid da etapa.

Dica

Para obter o sdkmessageprocessingstepid de uma determinada etapa, consulte as etapas de consulta registradas para um WebHook abaixo.

API Web:

GET [organization URI]/api/data/v9.0/asyncoperations?$orderby=completedon desc&$filter=statuscode eq 31 and _owningextensionid_value eq @stepid&$select=name,friendlymessage,errorcode,message,completedon?@stepid=<stepid>

Mais informações: consultar dados usando a API Web

FetchXML:

<fetch>
  <entity name="asyncoperation" >
    <attribute name="name" />
        <attribute name="friendlymessage" />
    <attribute name="errorcode" />
    <attribute name="message" />
    <attribute name="completedon" />     
    <filter>
      <condition attribute="owningextensionid" operator="eq" value="<stepid>" />
    </filter>
    <order attribute="completedon" descending="true" />
  </entity>
</fetch>

Mais informações: Usar FetchXml para recuperar dados

Modo síncrono

Quando você optar por usar um modo de execução síncrono, qualquer falha será relatada novamente ao usuário do aplicativo com uma caixa de diálogo de erro Ponto de extremidade indisponível informando ao usuário que o ponto de extremidade de serviço do webhook pode estar configurado incorretamente ou não está disponível. A caixa de diálogo permitirá que você baixe um arquivo de log para obter detalhes sobre quaisquer erros.

Note

Use o modo síncrono quando for importante que a operação disparada pelo WebHook ocorra imediatamente ou se você quiser que toda a transação falhe, a menos que o conteúdo do WebHook seja recebido pelo serviço. Um registro de etapa do WebHook simples fornece opções limitadas para gerenciar falhas, mas você também pode invocar Webhooks usando plug-ins e atividades de fluxo de trabalho se você precisar de mais controle. Para obter mais informações, consulte Chamar um WebHook a partir de um plug-in ou de uma atividade de fluxo de trabalho.

Etapas de consulta registradas para um webhook

Os dados dos webhooks registrados estão na tabela SdkMessageProcessingStep.

Você pode consultar as etapas registradas para um webhook específico quando souber o serviceendpointid do webhook. Consulte Consultar registros de webhook para ver uma consulta que obtém o ID de um webhook registrado.

API Web:

Use esta consulta da API da Web em que <id> é o ServiceEndpointId do webhook:

GET [organization URI]/api/data/v9.0/serviceendpoints(@id)/serviceendpoint_sdkmessageprocessingstep?$select=sdkmessageprocessingstepid,name,description,asyncautodelete,filteringattributes,mode,stage?@id=<id>

Para obter mais informações sobre a etapa registrada, use esta consulta da API Web, em que <stepid> é o SdkMessageProcessingStepId da etapa:

GET [organization URI]/api/data/v9.0/sdkmessageprocessingsteps(@id)?$select=name,description,filteringattributes,asyncautodelete,mode,stage&$expand=plugintypeid($select=friendlyname),eventhandler_serviceendpoint($select=name),sdkmessagefilterid($select=primaryobjecttypecode),sdkmessageid($select=name)?@id=<stepid>

FetchXML:

Use este FetchXML para obter as mesmas informações em uma única consulta, em que <serviceendpointid> é o ID do webhook:

<fetch>
  <entity name="sdkmessageprocessingstep" >
    <attribute name="name" />
    <attribute name="filteringattributes" />
    <attribute name="stage" />
    <attribute name="asyncautodeletename" />
    <attribute name="description" />
    <attribute name="mode" />
    <link-entity name="serviceendpoint" from="serviceendpointid" to="eventhandler" link-type="inner" alias="endpnt" >
      <attribute name="name" />
      <filter>
        <condition attribute="serviceendpointid" operator="eq" value="<serviceendpointid>" />
      </filter>
    </link-entity>
    <link-entity name="sdkmessagefilter" from="sdkmessagefilterid" to="sdkmessagefilterid" link-type="inner" alias="fltr" >
      <attribute name="primaryobjecttypecode" />
    </link-entity>
    <link-entity name="sdkmessage" from="sdkmessageid" to="sdkmessageid" link-type="inner" alias="msg" >
      <attribute name="name" />
    </link-entity>
  </entity>
</fetch>

Próximas Etapas 

Teste o registro de webhook com um site de registro de solicitações
Usar webhooks para criar manipuladores externos para eventos de servidor