Crochets Web

Les webhooks permettent aux développeurs d'enregistrer des URL qui reçoivent des notifications d'événements pour les utilisateurs via HTTP. Chaque webhook enregistré est identifié de manière unique par un identifiant unique au niveau mondial ; toutes les opérations suivantes prennent cet identifiant dans le chemin d'accès à la ressource.

Points finaux externes

Les webhooks doivent prendre en charge POST et répondre avec un statut Http 200 dans le délai requis, sinon la livraison sera retentée. Les notifications des webhooks sont retentées au maximum 5 fois, avec une pause de 10 secondes entre les tentatives, avant que le webhook ne soit marqué comme ayant échoué. Les événements ultérieurs ne sont pas transmis aux webhooks qui ont échoué. Le renouvellement d'un webhook efface son statut d'échec et permet de recevoir à nouveau des notifications d'événements.

Les points de terminaison des webhooks doivent répondre en temps utile. Notre système doit être en mesure d'établir une connexion avec le serveur URL du webhook dans les 3 secondes et le statut Http 200 doit être reçu dans les 2 secondes pour que la livraison du webhook soit considérée comme un succès.

Expiration

Les enregistrements de webhooks expirent au bout d'un certain temps (expireAt(généralement 10 jours), après quoi ils ne recevront plus de notifications. Les webhooks expirés (ou non expirés) peuvent toutefois être renouvelés indéfiniment. Les webhooks expirés seront définitivement supprimés à un moment donné (purgeAt). Lorsqu'un webhook est renouvelé, le renewedAt et renewedBy sont réglées sur l'heure actuelle, et les propriétés expireAt et purgeAt sont réinitialisées à de nouvelles valeurs après que renewedAt.

Lorsqu'un webhook est renouvelé, l'indicateur d'échec est réinitialisé, mais les statistiques de livraison antérieures ne sont pas supprimées.

Métadonnées, signatures et déduplication

Pour chaque événement de notification du webhook, les métadonnées relatives à l'événement et à sa livraison peuvent être incluses dans l'en-tête HTTP, dans le corps de la requête elle-même ou ne pas être incluses du tout. L'en-tête metadataPolicy permet de contrôler la diffusion des métadonnées souhaitées.

Les métadonnées des webhooks sont constituées des propriétés suivantes :

Clé	Description
`signature`	La valeur hachée de l'événement webhook. Si la politique est HEADER, cette valeur est envoyée en tant que X-VON-Signature.
`webhookId`	L'identifiant unique du webhook. Si la politique est HEADER, cette valeur est envoyée en tant que X-VON-Webhook-Id.
`deliveryId`	Un identifiant unique identifiant la livraison d'un événement spécifique. Si la politique est HEADER, cette valeur est envoyée en tant que X-VON-Delivery-Id.
`attempt`	Numbers le nombre de fois que l'événement a fait l'objet d'une tentative de livraison pour le même deliveryId. Si la politique est HEADER, cette valeur est envoyée en tant que X-VON-Attempt.

Pour que ces métadonnées soient délivrées, metadataPolicy doit être fixé à l'une des deux valeurs suivantes HEADER ou BODY. En outre, la signature n'est apposée que si signingAlgo est fixé à HMAC_SHA256 et un signingKey est défini.

Étant donné que le système tente à nouveau de livrer les entrées de webhook qui ont dépassé le délai, le point de terminaison lui-même doit savoir si plusieurs POST à une URL représentent le même événement ou un événement différent. Le point d'accès deliveryId et tentent de fournir au point final les informations nécessaires pour distinguer les événements de notification distincts des nouvelles tentatives.

Evénements

Les événements de notification Webhook ont le format suivant, par exemple :

{
    "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"
    }
}

Les metadata n'est incluse que si metadataPolicy est fixé à BODY. Les signatureune chaîne de caractères codée en hexadécimal, est calculée à partir de la valeur json de l'élément event où toutes les propriétés sont classées par ordre alphabétique, sans espace entre les noms des propriétés et leurs valeurs. Par exemple, la signature de l'exemple ci-dessus event serait calculé sur la base du json suivant :

{"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"}

Et en utilisant la clé secrète mysecretkey aurait la signature suivante :

95aafd08cb72b1f9216ccd002b8917b04e41ecb19276ae759241fdc0cbb53fb5.

Politique de réorientation

Les points de terminaison du webhook sont autorisés à renvoyer l'état Http 302 ou 307. Le système suivra les redirections jusqu'à une certaine limite, après quoi il marquera l'échec du webhook. Si le point de terminaison du webhook renvoie un état 302, l'événement du webhook est transmis sous la forme d'un Http Get à l'URL indiquée dans la réponse. Location . Si un 307 est renvoyé, l'événement du webhook est délivré sous la forme d'un POST Http à l'URL indiquée dans la réponse. Location l'en-tête.

Statistiques

Le système enregistre le nombre total de tentatives, de succès et d'échecs. Il enregistre également la date et l'heure du dernier succès et du dernier échec. Pour les échecs, le code d'état Http le plus récent et le message descriptif sont également conservés. Lorsqu'un webhook est renouvelé, seul le isFailed est réinitialisée à falsetoutes les autres statistiques sont conservées à des fins d'information.

Un webhook n'est pas considéré comme un succès ou un échec tant que toutes les tentatives de relance pour une livraison donnée n'ont pas été épuisées. Par exemple, si le système tente cinq fois une livraison de webhook et échoue, cela compte comme une seule tentative supplémentaire et un seul échec.

Les statistiques des webhooks peuvent être utilisées pour découvrir des événements qui risquent d'être manqués si l'URL est temporairement indisponible (par exemple, en raison d'une maintenance du système). Dans ce cas, les événements manqués peuvent être recherchés pour tout ce qui s'est passé après la fin de l'URL. lastSuccess. Il est conseillé de renouveler les webhooks existants immédiatement après la restauration d'un système à la suite d'une opération de maintenance.