Registrar un webhook

Utilice la herramienta de registro de complementos para registrar un webhook. Para obtener la herramienta de registro de complementos, consulte Herramientas de desarrollo de Dataverse.

En la herramienta de registro de complementos, seleccione la opción Registrar nuevo webhook.

Al registrar un webhook, debe proporcionar tres elementos de información:

Elemento	Descripción
Nombre	Un nombre único que describe el webhook.
URL del punto de conexión	La URL a la que enviar la información del contexto de ejecución.
Autenticación	Una de las tres opciones de autenticación. Para cualquier tipo de autenticación, debe proporcionar las claves que identifican la solicitud como legítima.

Los webhooks registrados solo admiten el puerto 80 para HTTP y el puerto 443 para HTTPS.

Opciones de autenticación

La opción y los valores de autenticación correctos para registrar el WebHook dependen de lo que espere el punto de conexión. El propietario del punto de conexión debe indicarte qué usar. Para usar webhooks con Microsoft Dataverse, el punto de conexión debe permitir una de las opciones de autenticación siguientes:

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 que usa code como clave y un valor requerido por el extremo. Al registrar el WebHook mediante la herramienta Registro de complementos, escriba solo el valor. Ejemplo: ?code=00000000-0000-0000-0000-000000000001
HttpQueryString	Incluye uno o varios pares de valor clave como parámetros de cadena de consulta. Ejemplo: ?Key1=Value1&Key2=Value2

Nota

La opción WebhookKey es útil con Azure Functions porque la cadena de consulta de autenticación espera un nombre de clave de code.

Se producirá un error en cualquier solicitud al punto de conexión configurado cuando las opciones de autenticación pasadas en la solicitud no coincidan. El punto de conexión es responsable de esta condición.

Consultar registros de WebHook

Los registros de webhook se almacenan en la Tabla ServiceEndpoint y tienen un valor de Contrato de 8.

Puede encontrar detalles sobre los webhooks registrados consultando la tabla ServiceEndpoint.

API web:

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

Para obtener más información, consulte Consultar datos mediante la 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> 

Más información: Usar FetchXml para recuperar datos

La información detallada sobre el conjunto de valores de autenticación se encuentra en la propiedad AuthValue y no se puede recuperar.

Registrar un paso para un WebHook

Registrar un paso para un webhook es similar a registrar un paso para un complemento. La diferencia principal es que no se puede especificar ninguna información de configuración.

Como con un complemento, se especifican el mensaje y, cuando corresponde, la información sobre las tablas. También puede especificar en qué lugar de la canalización del evento se ejecutará el webhook, el modo de ejecución y si se eliminará algún AsyncOperation cuando la operación tenga éxito.

La información sobre la Nombre del paso y la Descripción se rellenará automáticamente en función de las opciones que elija, pero puede cambiarlas. Si no establece algunos Atributos de filtro para un mensaje que los admita, se le pedirá que lo haga como las prácticas recomendadas de rendimiento.

El modo de ejecución y depuración del registro de su webhook

La forma en que registre el WebHook afecta a su experiencia al depurar cuando las cosas no funcionan.

Modo asincrónico

Cuando se utiliza el modo de ejecución asincrónica, el sistema crea un trabajo del sistema (asyncoperation) para registrar el éxito o el error de la operación. Optar por eliminar el trabajo del sistema cuando se complete correctamente ahorra espacio en la base de datos.

El sistema registra los errores que se producen en trabajos del sistema. En la aplicación web, puede ir a Configuración>Sistema>Trabajos del sistema para revisar el estado de los webhooks. Hay un valor de Fallido para Motivo del estado. Abra la tarea del sistema que falló para ver los detalles que describen por qué falló.

Consultar trabajos asíncronos fallidos de un paso determinado

Cuando conozca el sdkmessageprocessingstepid de un paso determinado, puede consultar la tabla AsynchronousOperations para comprobar si hay errores. Puede usar el valor OwningExtensionId para filtrar los resultados para un paso registrado específico. Los siguientes ejemplos utilizan <stepid> para el sdkmessageprocessingstepid del paso.

Propina

Para obtener el sdkmessageprocessingstepid de un paso determinado, consulte Consultar los pasos registrados para un WebHook a continuación.

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>

Para obtener más información, consulte Consultar datos mediante la 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>

Más información: Usar FetchXml para recuperar datos

Modo sincrónico

Cuando decida usar un modo de ejecución sincrónica cualquier error se notificará al usuario de la aplicación con un diálogo de error Extremo no disponible que informa al usuario de que el extermo del servicio webhook puede estar configurado incorrectamente o no está disponible. El diálogo le permitirá descargar un archivo de registro para obtener los detalles de cualquier error.

Nota

Use el modo sincrónico cuando sea importante que la operación desencadenada por el WebHook se produzca inmediatamente o si desea que se produzca un error en toda la transacción a menos que el servicio reciba la carga del webHook. Un registro sencillo de pasos de WebHook proporciona opciones limitadas para administrar errores, pero también puede invocar webhooks mediante complementos y actividades de flujo de trabajo si necesita más control. Para obtener más información, vea Invocar un webHook desde un complemento o una actividad de flujo de trabajo.

Pasos de consulta registrados para un webhook

Los datos de los webhooks registrados están en la tabla SdkMessageProcessingStep.

Puede consultar los pasos registrados para un webhook específico cuando conozca el serviceendpointid del webhook. Consulte Consulta de registros de WebHook para obtener el identificador de un webhook registrado.

API web:

Use esta consulta de API web donde <id> es serviceEndpointId del webhook:

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

Para obtener más información sobre el paso registrado, use esta consulta de API web donde <stepid> es sdkMessageProcessingStepId para el paso:

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 obtener la misma información en una consulta donde <serviceendpointid> es el identificador del 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>

Pasos siguientes

Probar el registro del webhook con un sitio para registrar solicitudes
Utilizar webhooks para crear controladores externos de eventos de servidor