Webhooks

Os webhooks permitem que os desenvolvedores registrem URLs que recebem notificações de eventos para os usuários via HTTP. Cada webhook registrado é identificado de forma exclusiva por um ID globalmente único; todas as operações subsequentes utilizam esse ID no caminho do recurso.

Pontos finais externos

Os webhooks devem suportar a método POST e responder com um status HTTP 200 dentro do tempo limite exigido; caso contrário, a entrega será repetida. As notificações de webhooks são repetidas no máximo 5 vezes, com uma pausa de 10 segundos entre cada tentativa, antes que o webhook seja marcado como com falha. Eventos subsequentes não são entregues a webhooks com falha. A renovação de um webhook limpará seu status de “falha” e ele voltará a receber notificações de eventos.

Os endpoints de webhook devem responder em tempo hábil. Nosso sistema deve ser capaz de estabelecer uma conexão com o servidor da URL do webhook em até 3 segundos, e o código de status HTTP 200 deve ser recebido em até 2 segundos para que a entrega do webhook seja considerada bem-sucedida.

Vencimento

Os registros de webhooks expiram após um certo período de tempo (expireAt, normalmente 10 dias), após o que não receberão mais notificações. No entanto, os webhooks vencidos (ou não vencidos) podem ser renovados indefinidamente. Os webhooks vencidos serão eliminados permanentemente em algum momento (purgeAt). Quando um webhook é renovado, o renewedAt e renewedBy as propriedades são definidas com a hora atual, e o expireAt e purgeAt as propriedades são redefinidas com novos valores após renewedAt.

Quando um webhook é renovado, ele zera o indicador de falha, mas não remove nenhuma outra estatística de entrega anterior.

Metadados, assinaturas e deduplicação

Junto com cada evento de notificação de webhook, os metadados sobre o evento do webhook e sua entrega podem ser incluídos no cabeçalho HTTP, no próprio corpo da solicitação ou podem não ser incluídos. O metadataPolicy Essa propriedade controla a forma desejada de entrega dos metadados.

Os metadados do webhook consistem nas seguintes propriedades:

Para que esses metadados sejam fornecidos, metadataPolicy deve ser definido como HEADER ou BODY. Além disso, a assinatura só é definida se signingAlgo está definido como HMAC_SHA256 e um que não seja vazio signingKey está definido.

Como o sistema tenta novamente a entrega das entradas de webhook que atingiram o tempo limite, o próprio endpoint precisa saber se várias solicitações POST enviadas a uma URL representam o mesmo evento ou eventos diferentes. O deliveryId e as propriedades de tentativa fornecem ao endpoint as informações necessárias para distinguir entre eventos de notificação distintos e novas tentativas.

Eventos

Os eventos de notificação por webhook têm o seguinte formato, por exemplo:

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

O metadata a propriedade só é incluída se metadataPolicy está definido como BODY. O signature, uma sequência codificada em hexadecimal, é calculada a partir do valor JSON do event propriedade, em que todas as propriedades são classificadas em ordem alfabética, sem espaços entre os nomes das propriedades ou seus valores. Por exemplo, a assinatura no exemplo acima event O corpo seria calculado com base no seguinte 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"}

E usando a chave secreta mysecretkey teria a seguinte assinatura:

95aafd08cb72b1f9216ccd002b8917b04e41ecb19276ae759241fdc0cbb53fb5.

Política de redirecionamento

Os endpoints de webhook podem retornar os códigos de status HTTP 302 ou 307. O sistema seguirá os redirecionamentos até um determinado limite; após esse limite, o sistema marcará o webhook como com falha. Se o endpoint do webhook retornar um 302, o evento do webhook será entregue como uma chamada HTTP GET para a URL encontrada na resposta Location cabeçalho. Se for retornado um código 307, o evento do webhook é enviado como uma solicitação HTTP POST para a URL indicada na resposta Location cabeçalho.

Estatísticas

O sistema registra o número total de tentativas, sucessos e falhas. Ele também registra a data e a hora do último sucesso e da última falha. No caso das falhas, o código de status HTTP mais recente e a mensagem descritiva também são registrados. Quando um webhook é renovado, apenas o isFailed a propriedade é redefinida para false; todas as demais estatísticas são mantidas apenas para fins informativos.

Um webhook não é considerado nem bem-sucedido nem malsucedido até que todas as tentativas de repetição para uma determinada entrega tenham sido esgotadas. Por exemplo, se o sistema tentar repetir a entrega de um webhook cinco vezes e falhar, isso conta como uma única tentativa adicional e uma única falha.

As estatísticas de webhooks podem ser usadas para identificar eventos que possam ter sido perdidos caso a URL fique temporariamente indisponível (por exemplo, devido a manutenção do sistema). Nesse caso, é possível consultar os eventos perdidos referentes a tudo o que ocorreu após lastSuccess. É recomendável renovar todos os webhooks existentes imediatamente após a restauração do sistema, após a manutenção.