Webhooks

Los webhooks permiten a los desarrolladores registrar URLs que reciben notificaciones de eventos para usuarios a través de HTTP. Cada webhook registrado se identifica unívocamente mediante un ID único global; todas las operaciones posteriores toman este ID en la ruta del recurso.

Puntos finales externos

Los webhooks deben soportar POST y responder con un Http Status 200 dentro del tiempo de espera requerido, de lo contrario la entrega será reintentada. Las notificaciones de webhooks se reintentan un máximo de 5 veces, con una pausa de 10 segundos entre reintentos, antes de que el webhook se marque como fallido. Los eventos posteriores no se envían a los webhooks fallidos. La renovación de un webhook borrará su estado "fallido" y comenzará a recibir notificaciones de eventos una vez más.

Los puntos finales de webhook deben responder a tiempo. Nuestro sistema debe ser capaz de establecer una conexión con el servidor URL del webhook en 3 segundos y el Estado Http 200 debe ser recibido en 2 segundos para que la entrega del webhook sea marcada como un éxito.

Caducidad

Los registros de webhooks caducan al cabo de cierto tiempo (expireAt(normalmente 10 días), transcurrido el cual dejarán de recibir notificaciones. Sin embargo, los webhooks caducados (o no caducados) pueden renovarse indefinidamente. Los webhooks caducados se eliminarán permanentemente en algún momento (purgeAt). Cuando se renueva un webhook, el renewedAt y renewedBy se ajustan a la hora actual, y las propiedades expireAt y purgeAt se restablecen a los nuevos valores después de renewedAt.

Cuando se renueva un webhook, se restablece el indicador de fallo, pero no se elimina ninguna otra estadística de entrega anterior.

Metadatos, firmas y deduplicación

Junto con cada evento de notificación webhook, los metadatos sobre el evento webhook y su entrega pueden incluirse en la cabecera HTTP, en el propio cuerpo de la petición, o no incluirse en absoluto. La dirección metadataPolicy controla la entrega de metadatos deseada.

Los metadatos Webhook constan de las siguientes propiedades:

Para que se entreguen estos metadatos, metadataPolicy debe establecerse en HEADER o BODY. Además, la firma sólo se establece si signingAlgo se establece en HMAC_SHA256 y un signingKey está fijado.

Dado que el sistema reintenta la entrega de las entradas de webhook que han expirado, el propio punto final necesita saber si varios POST a una URL representan el mismo evento o uno diferente. La dirección deliveryId y las propiedades de intento proporcionan al endpoint la información necesaria para distinguir entre eventos de notificación independientes y reintentos.

Eventos

Los eventos de notificación Webhook tienen el siguiente formato, por ejemplo:

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

En metadata sólo se incluye si metadataPolicy se establece en BODY. En signatureuna cadena codificada en hexadecimal, se calcula a partir del valor json del campo event donde todas las propiedades se ordenan alfabéticamente sin espacios en blanco entre los nombres de las propiedades o sus valores. Por ejemplo, la firma del ejemplo anterior event se calcularía sobre el siguiente json:

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

Y utilizando la clave secreta mysecretkey tendría la siguiente firma:

95aafd08cb72b1f9216ccd002b8917b04e41ecb19276ae759241fdc0cbb53fb5.

Política de redireccionamiento

Se permite que los puntos finales de webhook devuelvan el estado Http 302 o 307. El sistema seguirá las redirecciones, hasta cierto límite, después del cual, el sistema marcará el webhook como fallido. Si el webhook endpoint devuelve un 302, entonces el evento webhook se entrega como un Http Get a la URL encontrada en la respuesta Location encabezado. Si se devuelve un 307, entonces el evento webhook se entrega como un Http POST a la URL que se encuentra en la respuesta Location de cabeza.

Estadísticas

El sistema registra el número total de intentos, aciertos y fallos. También guarda la fecha/hora del último éxito y del último fracaso. En caso de fallo, también se guarda el último código de estado Http y el mensaje descriptivo. Cuando se renueva un webhook, sólo se guarda el isFailed vuelve a ser falseTodas las demás estadísticas se conservan con fines informativos.

Un webhook no se considera un éxito o un fracaso hasta que se hayan agotado todos los intentos de reintento para una entrega en particular. Por ejemplo, si el sistema reintenta la entrega de un webhook cinco veces y falla, cuenta como un único intento y fallo adicional.

Las estadísticas Webhook pueden utilizarse para descubrir eventos que potencialmente se pierden si la URL no está disponible temporalmente (por ejemplo, debido al mantenimiento del sistema). En tal caso, los eventos perdidos pueden ser consultados para todo lo que ocurrió después de lastSuccess. Es una buena práctica renovar los webhooks existentes inmediatamente después de restaurar un sistema tras su mantenimiento.