Visão Geral

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.
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.
• Configure o tempo limite, o número máximo de tentativas, a idade máxima do evento e o número máximo de conexões simultâneas, de acordo com suas necessidades.

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.