Webhooks
Atualizado em
Onde: Definições > Integrações > Webhooks
Para que serve:
"Encaminhe os eventos recebidos para o seu servidor." O SyBox envia uma cópia em tempo real de cada evento escolhido para um endereço no seu servidor. Os eventos do WhatsApp chegam no formato próprio da Meta. As mensagens dos clientes no Messenger, Instagram, Telegram, TikTok e Chat ao vivo, bem como os eventos de conversa (concluída, etiquetas, contatos, negócios, casos de CRM), chegam no formato próprio do SyBox. Mensagens de e-mail e SMS não são enviadas.
Quem tem permissão: administradores principais e usuários com a permissão "Gerenciar canais". Para criar ou religar um webhook, também é exigida a permissão "Mostrar o número do contato", já que o payload traz os telefones dos clientes.
Eventos suportados:
- "Mensagem recebida": um cliente enviou uma nova mensagem.
- "Estado da mensagem": confirmação de envio, entrega, leitura ou falha do disparo.
- "Reação": o cliente reagiu a uma mensagem com emoji.
- "Conversa marcada como concluída": uma conversa foi marcada como concluída por um membro da equipe, por uma automação ou sozinha após o silêncio do cliente.
- "Etiqueta adicionada ou removida": uma etiqueta foi adicionada a uma conversa ou removida dela.
- "Contato criado ou atualizado": um novo contato foi criado, ou o nome, e-mail ou campos de um contato mudaram. A importação de contatos não envia esses eventos.
- "Negócio fechado": um negócio foi registrado em uma conversa.
- "Caso de CRM aberto ou fechado": um caso de CRM foi aberto, ou fechado como resolvido, não resolvido ou cancelado. Um caso não pertence a nenhum número, portanto apenas um webhook que cubra todos os números o recebe, e não um limitado a alguns números.
Os cinco últimos chegam no formato próprio do SyBox, para todos os canais. A página Documentação do Desenvolvedor mostra um exemplo de cada um.
- "Transcrição de voz" (opcional): o áudio aguarda até cerca de dois minutos para que o texto processado acompanhe a notificação. Esse recurso vem desativado por padrão.
- Acesse Definições > Integrações > Webhooks.
- Clique em "Adicionar webhook".
- Insira o "Nome".
- Preencha a "URL do destino". O campo exige "Um endereço https público que possamos alcançar". Links em http comum ou IPs internos de rede local são rejeitados.
- Na seção "Eventos", selecione ao menos uma das opções ("Mensagem recebida" já vem marcada).
- Opcional: marque "Transcrição de voz" se quiser receber o áudio já convertido em texto.
- Em "Números", mantenha "Todos os números" para escutar todas as linhas ou desmarque para apontar números específicos.
- Clique em Salvar.
- A tela exibirá a "Chave de assinatura". "Copie agora — só é mostrada uma vez" e guarde-a no seu ambiente.
Detalhes de entrega:
- A estrutura do payload segue as especificações oficiais dos webhooks do WhatsApp da Meta.
- As chamadas são assinadas com a chave de autenticação no mesmo padrão adotado pela Meta. Se a sua API já valida requisições da Meta, basta apontar a verificação para o segredo do SyBox.
- Se o seu servidor não responder com status 200, o SyBox fará novas tentativas automáticas espaçadas ao longo de aproximadamente uma hora antes de descartar o evento.
- Falhas de conexão temporárias podem ocasionar envios duplicados do mesmo evento; sua aplicação deve tratar requisições repetidas.
- Certifique-se de que o webhook está ativado. Se estiver desativado, você verá "Ative este webhook primeiro."
- No cartão dele, clique em "Enviar evento de teste". Você verá "Um evento de teste está a caminho. O resultado aparece em Entregas."
- Alguns segundos depois, a lista "Entregas" se abre e mostra a resposta do seu servidor. O cartão também exibirá a última resposta retornada pelo seu sistema com o horário exato. Retornos positivos (ex.: "HTTP 200") aparecem em verde, e falhas em vermelho. A mensagem "Último envio: nunca" indica ausência de registros prévios.
Um evento de teste tem "event": "test" e não carrega dados de clientes. Você pode enviar um a cada poucos segundos; se tentar antes, verá "Um teste foi enviado há instantes. Tente novamente em alguns segundos."
- No cartão do webhook, clique em "Entregas".
- A lista mostra "As últimas 50 entregas dos últimos 7 dias.", da mais recente para a mais antiga. Cada uma mostra o evento, quando foi tentada e o seu estado:
- "Entregue": seu servidor respondeu com sucesso.
- "Aguardando envio": ainda não foi tentada.
- "Falhou, tentando novamente": seu servidor não respondeu com sucesso e o SyBox tentará novamente mais tarde.
- "Não entregue": o SyBox parou de tentar.
- Ela também mostra o código HTTP respondido pelo seu servidor, quanto tempo a resposta levou em milissegundos e "Tentativas: [número]" quando houve mais de uma tentativa. A mensagem em si não é exibida.
- Para enviar uma novamente, clique em "Enviar novamente" em uma entrega que esteja como "Entregue" ou "Não entregue". Você verá "Na fila para ser enviado novamente." Enviar novamente exige a permissão "Mostrar o número do contato", pois reenvia os dados do cliente.
Desativado sozinho:
Se o seu servidor continuar falhando — 20 tentativas seguidas, por mais de uma hora —, o SyBox desativa o webhook. O cartão mostra em vermelho "Desativado sozinho após [número] entregas com falha seguidas", e o administrador principal recebe uma notificação: "Um webhook foi desativado". Os eventos pendentes são mantidos por 24 horas. Corrija o endereço ou o seu servidor e ative o webhook novamente: os eventos pendentes serão enviados e a contagem recomeçará do zero.
- Clique em Editar para alterar nome, link de entrega, tipos de eventos ou linhas associadas.
- Para redefinir o segredo de autenticação, insira um novo código em "Chave de assinatura". Deixe o campo vazio para não mexer no segredo atual ("Deixe em branco para manter a chave atual").
- Use Ativar / Desativar para pausar os envios. Notificações ocorridas durante a pausa ficam enfileiradas e serão entregues caso o webhook volte a operar logo em seguida.
- Clique em Excluir e confirme em "Eliminar este webhook?".
Regras do formulário:
- O preenchimento do Nome, da URL de destino e a seleção de ao menos um evento são obrigatórios, sob risco de aviso de "Dados incompletos".
- Links que não utilizem https público serão bloqueados com o aviso "Um endereço https público que possamos alcançar".
Perdi minha chave de assinatura do webhook.
O segredo não pode ser recuperado visualmente. Edite o webhook, digite uma nova chave arbitrária em "Chave de assinatura", salve e configure essa mesma credencial no seu código.
Meu webhook foi desativado e não fui eu.
O SyBox o desativou depois que o seu servidor falhou 20 vezes seguidas por mais de uma hora. Veja "Desativado sozinho" acima: corrija o seu servidor e ative o webhook novamente dentro de 24 horas para que os eventos pendentes sejam enviados.
O webhook não registra nenhum envio.
Primeiro clique em "Enviar evento de teste" no cartão dele e olhe em "Entregas". Depois cheque estas quatro etapas: (1) O webhook está ativado; (2) Ao menos um evento foi selecionado; (3) O filtro inclui o número certo de WhatsApp ou "Todos os números"; (4) O canal pelo qual a mensagem chegou é um dos canais atendidos pelos webhooks (WhatsApp, Messenger, Instagram, Telegram, TikTok ou Chat ao vivo; não e-mail nem SMS). Por fim, analise o retorno da última tentativa gravado no cartão.
O status do envio acusa falha com HTTP 404 ou 500 em vermelho.
O SyBox conseguiu contatar o seu servidor, mas o seu endpoint retornou um erro interno. Verifique o caminho da rota e consulte os logs da sua aplicação.
Não consigo salvar um webhook por falta de permissão.
Para cadastrar ou ligar um webhook, seu usuário precisa simultaneamente das permissões "Gerenciar canais" e "Mostrar o número do contato". Contate o administrador da sua conta.