Webhooks
Os webhooks permitem que o SIP Caller notifique seus sistemas em tempo real quando algo acontece na sua conta, como a ativação de uma campanha ou o término de uma chamada. Em vez de consultar a API REST periodicamente em busca de alterações, sua aplicação expõe um endpoint HTTPS, e o SIP Caller envia para ele uma solicitação HTTP POST com um payload JSON toda vez que ocorre um evento assinado.
Para começar a receber webhooks, crie um webhook no Console Web, selecione os eventos do seu interesse, e atribua-o às suas campanhas. Consulte Webhooks para um guia passo a passo.
Payload do evento
Toda solicitação de webhook tem um corpo JSON com o mesmo envelope, em que o campo data contém os detalhes do evento:
{
"id": "01928321-9129-7f25-8ad3-80c57b16d3ed",
"object": "event",
"apiVersion": 2,
"createdAt": "2024-10-12T23:47:48.133",
"type": "CampaignActivated",
"data": {
...
}
}| Campo | Descrição |
|---|---|
id | Identificador único do evento. Se o mesmo evento for entregue mais de uma vez (por exemplo, após uma nova tentativa), ele mantém o mesmo id, para que você possa usá-lo para descartar duplicatas. |
object | Sempre event. |
apiVersion | Versão do formato do payload, conforme configurada no webhook. |
createdAt | Data e hora em que o evento ocorreu. |
type | Tipo do evento, como CampaignActivated ou CallEnded. |
data | Detalhes do evento. Seu conteúdo depende do tipo de evento, conforme descrito na página de cada evento. |
Versões
Todo webhook é configurado com uma versão de payload. Quando o SIP Caller introduz nos payloads alterações que não são retrocompatíveis, ele as lança em uma nova versão, para que as integrações existentes continuem recebendo o formato que esperam. Recomendamos usar a versão mais recente para novas integrações. A página de cada evento inclui um seletor de versão que mostra o payload de cada versão.
Tipos de eventos
| Evento | Tipo | Enviado quando |
|---|---|---|
| Campanha ativada | CampaignActivated | Uma campanha é ativada. |
| Campanha pausada | CampaignPaused | Uma campanha ativa é pausada. |
| Campanha retomada | CampaignResumed | Uma campanha pausada é retomada. |
| Campanha cancelada | CampaignCanceled | Uma campanha é cancelada. |
| Campanha finalizada | CampaignFinished | Uma campanha é finalizada. |
| Chamada finalizada | CallEnded | Uma chamada feita por uma campanha termina. |
Verificar assinaturas
Toda solicitação de webhook inclui um cabeçalho Sip-Caller-Signature, que permite verificar que a solicitação foi enviada pelo SIP Caller e não foi modificada:
Sip-Caller-Signature: t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efaeO valor t é o timestamp em que o evento foi assinado, e o valor v1 é a assinatura. Para verificá-la:
- Concatene o timestamp (como uma string), um ponto (
.), e o corpo JSON bruto da solicitação, exatamente como foi recebido. - Calcule um HMAC com a função de hash SHA-256, usando o segredo de assinatura do webhook como chave e a string concatenada como mensagem.
- Compare o resultado, em hexadecimal, com o valor
v1. Processe o evento somente se ambos os valores coincidirem.
Por exemplo, em Python:
import hashlib
import hmac
def is_valid_signature(header: str, body: bytes, secret: str) -> bool:
parts = dict(item.split("=", 1) for item in header.split(","))
message = parts["t"].encode() + b"." + body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])Há exemplos completos disponíveis para Python e .NET. O segredo de assinatura pode ser regenerado no Console Web; quando fizer isso, atualize sua aplicação imediatamente, pois as assinaturas feitas com o novo segredo não serão validadas com o antigo.
Responder rapidamente
Seu endpoint deve responder com um código de status 2xx assim que receber o evento, e fazer qualquer processamento demorado depois (por exemplo, em um job em segundo plano). Se o seu endpoint não responder a tempo, ou responder com um erro, o SIP Caller tenta a entrega novamente de acordo com as configurações de tempo limite e de novas tentativas do webhook. Como um evento pode ser entregue mais de uma vez, torne seu processamento idempotente usando o id do evento.
