Webhaken

Webhooks ermöglichen es Entwicklern, URLs zu registrieren, die Benachrichtigungen über Ereignisse für Benutzer über HTTP empfangen. Jeder registrierte Webhook wird durch eine global eindeutige ID eindeutig identifiziert; alle nachfolgenden Operationen übernehmen diese ID in den Ressourcenpfad.

Externe Endpunkte

Webhooks müssen POST unterstützen und mit einem Http-Status 200 innerhalb der erforderlichen Zeitspanne antworten, andernfalls wird die Zustellung erneut versucht. Webhook-Benachrichtigungen werden maximal 5 Mal wiederholt, wobei zwischen den Wiederholungen eine Pause von 10 Sekunden eingelegt wird, bevor der Webhook als fehlgeschlagen markiert wird. Nachfolgende Ereignisse werden nicht an fehlgeschlagene Webhooks zugestellt. Wenn Sie einen Webhook erneuern, wird sein Status "fehlgeschlagen" gelöscht und Sie erhalten wieder Ereignisbenachrichtigungen.

Webhook-Endpunkte müssen zeitnah reagieren. Unser System muss in der Lage sein, innerhalb von 3 Sekunden eine Verbindung zum Webhook-URL-Server herzustellen, und der Http-Status 200 muss innerhalb von 2 Sekunden empfangen werden, damit die Webhook-Übermittlung als Erfolg gewertet wird.

Verfallsdatum

Webhook-Registrierungen laufen nach einer bestimmten Zeit ab (expireAt(in der Regel 10 Tage), nach deren Ablauf sie keine Benachrichtigungen mehr erhalten. Abgelaufene (oder nicht abgelaufene) Webhooks können jedoch auf unbestimmte Zeit verlängert werden. Abgelaufene Webhooks werden zu einem bestimmten Zeitpunkt dauerhaft gelöscht (purgeAt). Wenn ein Webhook erneuert wird, wird der renewedAt und renewedBy werden auf die aktuelle Zeit gesetzt, und die Eigenschaften expireAt und purgeAt Eigenschaften werden auf neue Werte zurückgesetzt, nachdem renewedAt.

Wenn ein Webhook erneuert wird, wird die Fehlermarkierung zurückgesetzt, aber es werden keine anderen vergangenen Zustellungsstatistiken gelöscht.

Metadaten, Signaturen und Deduplizierung

Zusammen mit jedem Webhook-Benachrichtigungsereignis können Metadaten über das Webhook-Ereignis und seine Zustellung entweder in den HTTP-Header, den Request-Body selbst oder gar nicht aufgenommen werden. Die metadataPolicy Eigenschaft steuert die gewünschte Metadatenübermittlung.

Webhook-Metadaten bestehen aus den folgenden Eigenschaften:

Damit diese Metadaten geliefert werden können, metadataPolicy muss entweder auf HEADER oder BODY. Außerdem wird die Signatur nur gesetzt, wenn signingAlgo wird eingestellt auf HMAC_SHA256 und eine nicht leere signingKey eingestellt ist.

Da das System die Zustellung von Webhook-Einträgen, bei denen die Zeit abgelaufen ist, wiederholt, muss der Endpunkt selbst wissen, ob mehrere POSTs an eine URL das gleiche oder ein anderes Ereignis darstellen. Der deliveryId und Versuchseigenschaften liefern dem Endpunkt die notwendigen Informationen, um zwischen separaten Benachrichtigungsereignissen und Wiederholungsversuchen zu unterscheiden.

Veranstaltungen

Webhook-Benachrichtigungsereignisse haben z. B. das folgende Format:

{
    "event": {
        "accountId": "-1",
        "direction": "OUTBOUND",
        "duration": 0,
        "externalId": "abc1234-288c-40d3-8ec8-3618a3ae7698_123",
        "id": "abc1234a806d07a6ff17ba",
        "internal": false,
        "phoneNumber": "xxxxxxxxxx",
        "startTime": "2020-10-01T16:10:06.000+0000",
        "state": "RINGING",
        "type": "CALL",
        "ucpType": "VBS",
        "userId": "1234"
    },
    "metadata": {
        "attempt": 1,
        "deliveryId": "abc1234-2795-446c-be6b-7cba85c6bba2",
        "signature": "abc1234663a4d0589ec092677b4af18b4a747ac8cfa6198a57b8c6bfec9bf28a",
        "webhookId": "abc1234-c1ad-4a14-a30b-69dd92f57af2"
    }
}

Die metadata ist nur enthalten, wenn metadataPolicy wird eingestellt auf BODY. Die signatureeine hexadezimal kodierte Zeichenkette, wird aus dem json-Wert der Datei event Eigenschaft, wobei alle Eigenschaften alphabetisch sortiert sind und keine Leerzeichen zwischen den Eigenschaftsnamen oder ihren Werten stehen. Die Signatur des obigen Beispiels ist zum Beispiel event Körper würde auf dem folgenden json berechnet werden:

{"accountId": "-1","direction": "OUTBOUND","duration": 0,"externalId": "abc1234-288c-40d3-8ec8-3618a3ae7698_123","id": "abc1234a806d07a6ff17ba","internal": false,"phoneNumber": "xxxxxxxxxx","startTime": "2020-10-01T16:10:06.000+0000","state": "RINGING","type": "CALL","ucpType": "VBS","userId": "1234"}

Und unter Verwendung des geheimen Schlüssels mysecretkey würde die folgende Signatur haben:

95aafd08cb72b1f9216ccd002b8917b04e41ecb19276ae759241fdc0cbb53fb5.

Umleitungspolitik

Webhook-Endpunkte dürfen entweder den Http-Status 302 oder 307 zurückgeben. Das System folgt den Weiterleitungen bis zu einer gewissen Grenze, danach wird der Webhook als fehlgeschlagen markiert. Wenn der Webhook-Endpunkt ein 302 zurückgibt, wird das Webhook-Ereignis als Http-Get an die in der Antwort gefundene URL geliefert Location Kopfzeile. Wenn ein 307 zurückgegeben wird, wird das Webhook-Ereignis als Http-POST an die in der Antwort gefundene URL geliefert Location Kopfzeile.

Statistik

Das System erfasst die Gesamtzahl der Versuche, Erfolge und Misserfolge. Es speichert auch das Datum und die Uhrzeit des letzten Erfolgs und Fehlschlags. Bei Fehlschlägen werden auch der letzte Http-Statuscode und die beschreibende Meldung gespeichert. Wenn ein Webhook erneuert wird, wird nur die isFailed Eigenschaft wird zurückgesetzt auf falseAlle anderen Statistiken werden zu Informationszwecken geführt.

Ein Webhook wird erst dann als Erfolg oder Misserfolg gewertet, wenn alle Wiederholungsversuche für eine bestimmte Zustellung ausgeschöpft sind. Wenn das System beispielsweise eine Webhook-Zustellung fünfmal wiederholt und fehlschlägt, wird dies als ein einziger zusätzlicher Versuch und Fehlschlag gewertet.

Webhook-Statistiken können verwendet werden, um Ereignisse zu ermitteln, die möglicherweise verpasst werden, wenn die URL vorübergehend nicht verfügbar ist (z. B. aufgrund von Systemwartungen). In einem solchen Fall können verpasste Ereignisse für alles abgefragt werden, was nach lastSuccess. Es ist eine gute Praxis, alle vorhandenen Webhooks unmittelbar nach der Wiederherstellung eines Systems nach einer Wartung zu erneuern.