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 admitir el método POST y responder con un código de estado HTTP 200 dentro del tiempo de espera establecido; de lo contrario, se volverá a intentar el envío. Las notificaciones de los webhooks se reintentan un máximo de 5 veces, con una pausa de 10 segundos entre cada intento, antes de que el webhook se marque como fallido. Los eventos posteriores no se envían a los webhooks fallidos. Al renovar un webhook, se borrará su estado de «fallido» y volverá a recibir notificaciones de eventos.

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

Las inscripciones en los webhooks caducan al cabo de un 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 de webhook, los metadatos sobre el evento de webhook y su envío pueden incluirse en el encabezado HTTP, en el propio cuerpo de la solicitud o no incluirse en absoluto. El metadataPolicy controla la entrega de metadatos deseada.

Los metadatos de los webhooks 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á configurado.

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

El metadata La propiedad solo se incluye si metadataPolicy se establece en BODY. En signatureuna cadena codificada en hexadecimal, se calcula a partir del valor json del campo event propiedad, donde todas las propiedades están ordenadas alfabéticamente sin espacios entre los nombres de las propiedades ni 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 código 307, el evento del webhook se envía mediante un método HTTP POST a la URL que figura en la respuesta Location de cabeza.

Estadísticas

El sistema registra el número total de intentos, éxitos y fallos. También registra la fecha y la hora del último éxito y del último fallo. En el caso de los fallos, también se guardan el código de estado HTTP más reciente y el mensaje descriptivo. Cuando se renueva un webhook, solo el isFailed la propiedad vuelve a establecerse en false; el resto de estadísticas se recogen con fines informativos.

Un webhook no se considera ni un éxito ni un fallo hasta que se hayan agotado todos los intentos de reenvío correspondientes a una entrega concreta. Por ejemplo, si el sistema reintenta el envío de un webhook cinco veces y falla, se cuenta como un único intento adicional y un único fallo.

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. Se recomienda renovar todos los webhooks existentes inmediatamente después de que se haya restablecido el sistema tras unas tareas de mantenimiento.