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:

Item	Descripción
Nombre	Un nombre único que describa el webhook.
URL de extremo	La URL para publicar información de 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 identificarán 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 correctos de autenticación de registro de webhook que se van a utilizar dependen de lo que se espere del punto de conexión. El propietario del extremo debe indicarle qué utilizar. Para usar webhooks con Microsoft Dataverse, el punto de conexión debe permitir una de las opciones de autenticación siguientes:

Type	Descripción
HttpHeader	Incluye uno o varios pares de valores clave en el encabezado de la solicitud http. Ejemplo: Key1: Value1 Key2: Value2
WebhookKey	Incluye una cadena de consulta mediante code como clave y un valor requerido para el punto de conexión. Al registrar el webhook mediante la herramienta de 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 funciones de Azure porque se espera que la cadena de consulta de autenticación tenga un nombre de clave de code.

Cualquier solicitud para el extremo configurado debe fallar cuando no coinciden las opciones de autenticación pasadas en la solicitud. El punto de conexión es responsable de esto.

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: Uso de FetchXML con FetchExpression

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.

Al igual que un complemento, especifique el mensaje y la información sobre las tablas cuando corresponda. 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

Su elección al registrar el webhook cambia la experiencia que tendrá al depurar si se producen errores.

Modo asincrónico

Cuando utilice un modo de ejecución asincrónica, se creará un trabajo del sistema (asyncoperation) para capturar el éxito o fracaso de la operación. Si elimina el trabajo del sistema cuando tiene éxito ahorrará espacio en la base de datos.

Cualquier error que se produzca se registrará en los trabajos del sistema. En la aplicación web, puede ir a Configuración > Sistema > Trabajos del sistema para revisar el estado de los webhooks. Habrá un valor Razón para el estado de Erróneo. Abra el trabajo del sistema con errores para encontrar detalles que describan la razón por la que falló el trabajo.

Consultar trabajos asincrónicos que dan error para un paso determinado

Cuando conozca el sdkmessageprocessingstepid de un paso determinado, puede consultar la Tabla AsynchronousOperations para ver cualquier error. 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.

Sugerencia

Para obtener el sdkmessageprocessingstepid de un paso dado, consulte Consultar 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: Uso de FetchXML con FetchExpression

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

Debe usar el modo sincrónico cuando sea importante que la operación desencadenada por el webhook se produzca de inmediato o si desea que toda la transacción falle a menos que el servicio reciba la carga de webhook. Un registro simple de paso de webhook proporciona opciones limitadas para administrar los errores, pero también puede llamar a webhooks mediante actividades de flujo de trabajo y complementos si necesita más control. Más información: Llamar a un webhook desde una actividad de flujo de trabajo o complemento.

Pasos de consulta registrados para un webhook

Los datos para webhooks registrados se encuentran en la Tabla SdkMessageProcessingStep.

Puede consultar los pasos registrados para un webhook específico cuando conozca el serviceendpointid para el webhook. Vea Consultar registros de webhook para hacer una consulta para obtener el id. de un webhook registrado.

API web:

Puede usar esta consulta de API web en la que <id> es el 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, puede usar esta consulta de API web en la que <stepid> es el 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:

Puede usar este FetchXML para obtener la misma información en una consulta en la que <serviceendpointid> es el id. 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 de webhook con un sitio de registro de solicitud
Utilizar webhooks para crear controladores externos de eventos de servidor

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).