Webhooks

O SIP Caller pode acionar webhooks para notificar sistemas externos sobre eventos que acontecem em nossa plataforma. Dessa forma, muitas integrações personalizadas úteis podem ser desenvolvidas entre o SIP Caller e outros sistemas. Os webhooks requerem o plano Enterprise.
O procedimento envolve 2 etapas:

1. Criar um webhook.
2. Configurar uma campanha com um webhook existente.

Criar um webhook

Para criar um webhook, faça login no SIP Caller e vá em Configurações > Webhooks. Depois clique no botão "Criar" para abrir a caixa de diálogo de criação de Webhook e proceda da seguinte forma:

• Digite um nome amigável para o webhook, para que você possa selecioná-lo facilmente depois.
• Digite a URL que você deseja que o SIP Caller invoque quando os eventos ocorrerem.
• Selecione a versão. Recomendamos usar a versão mais recente para aproveitar os recursos mais novos, mas você também pode configurar uma versão anterior por motivos de retrocompatibilidade.
• Selecione os eventos de seu interesse. Os eventos disponíveis estão descritos em Tipos de eventos.
• Configure as opções avançadas de acordo com suas necessidades. Ao criar um webhook, elas têm os seguintes valores padrão:
  • Tempo de espera em segundos: 30. O tempo que o SIP Caller aguarda a resposta do seu endpoint.
  • Máximo de tentativas: 5. O número máximo de vezes que o SIP Caller tenta entregar cada evento.
  • Idade máxima do evento em horas: 24. Os eventos que aguardam envio por mais tempo do que isso, por exemplo enquanto o webhook está desabilitado, são descartados.
  • Máximo de conexões simultâneas: 8. O número máximo de solicitações que o SIP Caller envia ao seu endpoint ao mesmo tempo.

Tipos de eventos

Um webhook pode notificar os seguintes eventos:

• Campanha ativada: uma campanha é ativada, por um usuário no console do SIP Caller ou por uma aplicação por meio da API REST.
• Campanha pausada: uma campanha ativa é pausada.
• Campanha retomada: uma campanha pausada é ativada novamente.
• Campanha cancelada: uma campanha é cancelada.
• Campanha finalizada: uma campanha é finalizada.
• Chamada finalizada: uma chamada feita por uma campanha termina, qualquer que seja o seu resultado.

Os eventos de campanha contêm a configuração da campanha e, quando a alteração foi feita por um usuário ou por uma aplicação, a origem da alteração. O evento Chamada finalizada contém os detalhes da chamada: o número chamado e os valores de suas variáveis, os resultados do toque e do atendimento, as durações, os resultados das interações com o contato (como entradas DTMF ou objetivos do agente de IA), os detalhes da transferência, e o desfecho final da chamada, incluindo quando ela será repetida. Este é o evento a ser usado para atualizar seus próprios sistemas, como um CRM, com o resultado de cada chamada.

Entrega e novas tentativas

Cada evento é enviado como uma solicitação HTTP POST para a URL do webhook, com um payload JSON e o cabeçalho "Sip-Caller-Signature", para que seu endpoint possa validar que a solicitação foi enviada pelo SIP Caller.

A entrega é bem-sucedida quando seu endpoint responde com um código de status HTTP 2xx dentro do tempo de espera configurado. Quando o endpoint responde com qualquer outro código de status, não responde a tempo, ou não pode ser alcançado, a entrega falha, e o SIP Caller a repete automaticamente: a primeira nova tentativa é feita 5 minutos após a tentativa com falha, a segunda 1 hora depois, a terceira 4 horas depois, e cada nova tentativa seguinte aguarda 4 horas a mais do que a anterior, até atingir o máximo de tentativas. Após a última tentativa, o evento é marcado como falho.

Cada tentativa de entrega é registrada, junto com seu resultado, o código de resposta e o tempo de resposta, para que você possa verificar o status de cada evento conforme descrito em Solução de problemas de webhooks.

Configurar uma campanha para acionar webhooks

Depois que o webhook for criado, você precisa configurar as campanhas para usá-lo. Para fazer isso, basta selecionar o webhook na aba Integração.

Habilitar e desabilitar webhooks

Se você encontrar um problema ao processar os webhooks acionados pelo SIP Caller, pode pausar a geração desses eventos. Ao fazer isso, o SIP Caller enfileirará esses eventos durante o tempo que você configurou ao criá-lo, dando a você tempo para corrigir seu algoritmo de processamento de eventos, para que possa então habilitar os webhooks novamente. Para fazer isso, vá em Configurações > Webhooks, e selecione os botões "Habilitar" ou "Desabilitar" na coluna Ações.

Regenerar o segredo de assinatura

Na coluna Ações da lista de webhooks, você também pode clicar no botão para regenerar o segredo de assinatura. Isso fará com que o SIP Caller comece a assinar os webhooks usando o novo segredo. Qualquer integração que você tenha usando o segredo antigo deixará de funcionar, pois a validação falhará, portanto você deve ter cuidado ao realizar essa ação.

Validar a assinatura do webhook

Toda notificação de webhook enviada pelo SIP Caller terá o cabeçalho "Sip-Caller-Signature" na solicitação HTTP, definido com um valor semelhante ao seguinte:

t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efae

O valor atribuído a "t" é um timestamp informando quando o evento foi gerado. O valor atribuído a "v1" é a assinatura do webhook. Você precisará dos dois valores para fazer a verificação, da seguinte forma:

1. Concatene o timestamp (como uma string), um ponto (.), e o payload JSON recebido no corpo da solicitação HTTP. Por exemplo:

   1728776932.{"id" : "01928322-860c-77f9-9c3b-7f8abe3b6afd".......}

2. Calcule a assinatura de webhook esperada, computando um HMAC usando a função de hash SHA256. Use o segredo de assinatura do webhook como a chave, e o valor resultante da concatenação da etapa anterior como a mensagem.
3. Compare a assinatura de webhook calculada com o valor obtido de "v1" no cabeçalho da solicitação. Se ambos os valores coincidirem, você pode prosseguir com segurança com o processamento do evento de webhook.

Criamos exemplos de código mostrando como fazer essa validação em uma aplicação Python ou .NET.

Solução de problemas de webhooks

No console do SIP Caller > Configurações > Webhooks, você pode clicar em um webhook e verificar todos os eventos que foram notificados.
A lista pode ser filtrada para identificar o evento que você está procurando. Em seguida, ao clicar em um evento, um painel será exibido no lado direito, com os detalhes de cada tentativa de notificação.

Referência de dados dos webhooks

Os webhooks gerados pelo SIP Caller são solicitações HTTP POST, contendo JSON como payload, e cada solicitação é identificada com uma versão para que possamos evoluir o formato do payload ao longo do tempo sem quebrar integrações existentes. A referência completa em JSON para cada tipo de evento e versão está disponível na página de Referência de dados dos webhooks.