Registrieren eines Webhooks

Verwenden Sie das Plug-In-Registrierungstool, um einen Webhook zu registrieren. Um das Tool zur Plug-In-Registrierung zu erhalten, siehe Dataverse-Entwicklungstools.

Wählen Sie im Tool „Plug-in-Registrierung“ die Option Neuen Webhook registrieren aus.

Wenn Sie einen Webhook registrieren, müssen Sie drei Informationselemente bereitstellen:

Registrierte Webhooks unterstützen nur Port 80 für HTTP und Port 443 für HTTPS.

Authentifizierungsoptionen

Die richtige WebHook-Registrierungsauthentifizierungsoption und -werte hängen davon ab, was der Endpunkt erwartet. Der Besitzer des Endpunkts muss Ihnen mitteilen, was verwendet werden soll. Zum Verwenden von Webhooks mit Microsoft Dataverse muss der Endpunkt eine der folgenden Authentifizierungsoptionen zulassen:

Jede Anforderung an den konfigurierten Endpunkt sollte fehlschlagen, wenn die in der Anforderung übergebenen Authentifizierungsoptionen nicht übereinstimmen. Der Endpunkt ist für diese Bedingung verantwortlich.

WebHook-Registrierungen abfragen

WebHook-Registrierungen werden in der ServiceEndpoint-Tabelle gespeichert und haben einen Vertrag-Wert von 8.

Details zu den registrierten Webhooks finden Sie durch Abfrage der Tabelle ServiceEndpoint.

Web-API:

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

Weitere Informationen: Abfrage von Daten über die Web-API

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> 

Weitere Informationen: FetchXML zum Abrufen von Daten verwenden

Informationen zu den festgelegten Authentifizierungswerten sind in der AuthValue-Eigenschaft gespeichert und können nicht abgerufen werden.

Registrieren eines Schritts für einen WebHook

Das Registrieren eines Schritts für einen WebHook ist wie das Registrieren eines Schritts für ein Plug-In. Der Hauptunterschied ist, dass Sie keine Konfigurationsinformationen angeben können.

Genau wie bei einem Plug-In geben Sie die Nachricht und ggf. Informationen über Tabellen an. Sie können auch angeben, wo in der Ereignis-Pipeline der WebHook ausgeführt werden soll, den Ausführungsmodus und ob eine AsyncOperation gelöscht werden soll, wenn die Operation erfolgreich ist.

Informationen zu Schrittname und Beschreibung werden basierend auf den ausgewählten Optionen automatisch ausgefüllt, Sie können die Daten jedoch ändern. Wenn Sie für eine Nachricht, die diese unterstützt, keine Filterattribute festlegen, werden Sie gemäß den Best Practices zur Leistungsoptimierung dazu aufgefordert.

Ausführungsmodus und Debugging Ihrer WebHook-Registrierung

Ihre Wahl bei der Registrierung des Webhooks ändert die Erfahrung, die Sie beim Debuggen machen, wenn etwas nicht funktioniert.

Asynchroner Modus

Wenn Sie den asynchronen Ausführungsmodus verwenden, erstellt das System einen Systemauftrag (asyncoperation), um den Erfolg oder Fehler des Vorgangs zu erfassen. Wenn Sie sich dafür entscheiden, den Systemauftrag bei Erfolg zu löschen, sparen Sie Speicherplatz in der Datenbank.

Das System zeichnet alle Fehler auf, die in Systemaufträgen auftreten. In der Webanwendung können Sie zu Einstellungen>Systemsystemaufträge> wechseln, um den Status aller Webhooks zu überprüfen. Es gibt einen Statusgrund-Wert vom Typ Fehler. Öffnen Sie den fehlgeschlagenen System-Job, um Details zu finden, die beschreiben, warum der Job fehlgeschlagen ist.

Fehlgeschlagene asynchrone Aufträge für einen gegebenen Schritt abfragen

Wenn Sie die sdkmessageprocessingstepid eines bestimmten Schritts kennen, können Sie die Tabelle AsynchronousOperations nach Fehlern abfragen. Mit dem OwningExtensionId-Wert können Sie die Ergebnisse nach einem bestimmten registrierten Schritt filtern. Die folgenden Beispiele verwenden <stepid> für die sdkmessageprocessingstepid des Schritts.

Web-API:

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>

Weitere Informationen: Abfrage von Daten über die Web-API

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>

Weitere Informationen: FetchXML zum Abrufen von Daten verwenden

Synchroner Modus

Wenn Sie den synchronen Ausführungsmodus verwenden, werden alle Fehler dem Benutzer der Anwendung gemeldet. Dazu wird ein Endpunkt nicht verfügbar-Fehlerdialog angezeigt, der den Benutzer darüber informiert, dass der Webhook-Service-Endpunkt möglicherweise falsch konfiguriert oder nicht verfügbar ist. Im Dialogfeld können Sie eine Protokolldatei mit Informationen zu etwaigen Fehlern herunterladen.

Abfragen von Schritten, die für ein Webhook registriert sind

Daten für registrierte Webhooks befinden sich in der SdkMessageProcessingStep-Tabelle.

Sie können die für einen bestimmten Webhook registrierten Schritte abfragen, wenn Sie die serviceendpointid des Webhooks kennen. Siehe WebHook-Registrierungen abfragen für eine Abfrage, mit der Sie die ID eines registrierten Webhooks abrufen können.

Web-API:

Verwenden Sie diese Web-API-Abfrage, wobei <die ID> die ServiceEndpointId des Webhook ist:

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

Weitere Informationen zum registrierten Schritt finden Sie in dieser Web-API-Abfrage, bei der <"stepid>" die SdkMessageProcessingStepId für den Schritt ist:

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:

Verwenden Sie dieses FetchXML, um dieselben Informationen in einer Abfrage abzurufen, bei der <serviceendpointid> die ID des Webhooks ist:

<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>

Nächste Schritte,

Testen von Webhook-Registrierungen mit einer Website zur Anfragenprotokollierung
Verwenden Sie Webhooks zum Erstellen externer Handler für Serverereignisse