Integração com webhooks - guia completo de gatilhos HTTP

Os webhooks são a maneira mais versátil de acionar notificações do Echobell. Este guia completo cobre tudo o que você precisa saber para integrar alertas baseados em webhook aos seus sistemas, dos conceitos básicos aos padrões de uso mais avançados.

O que é um webhook

Um webhook é uma forma de um aplicativo fornecer informações em tempo real a outros aplicativos por meio de callbacks HTTP. Pense nele como um número de telefone que você dá a alguém: quando essa pessoa liga para o número, o seu telefone toca. No mundo digital, quando algo acontece em um sistema (como uso alto de CPU, uma falha de build ou um novo pedido), ele envia uma requisição HTTP para uma URL (o webhook) que você forneceu, acionando uma ação no seu sistema.

Por exemplo, quando o uso de CPU do seu servidor fica alto demais, o seu sistema de monitoramento pode chamar a URL de webhook do Echobell, que então aciona uma notificação para avisar você. Isso acontece automaticamente e em tempo real, sem que você precise ficar verificando o uso de CPU por conta própria.

Os webhooks são a base das arquiteturas orientadas a eventos e têm suporte em praticamente todos os serviços de nuvem, ferramentas de monitoramento e plataformas SaaS modernos. Eles são leves, rápidos e não exigem nenhuma infraestrutura especial do seu lado - basta um cliente HTTP.

Vantagens dos webhooks

Tempo real: os eventos acionam notificações na hora, normalmente em 1 a 2 segundos
Universais: têm suporte em quase todos os serviços e linguagens de programação modernos
Flexíveis: passe dados personalizados para criar notificações ricas e cheias de contexto
Confiáveis: baseados em HTTP, com códigos de status e tratamento de erros padronizados
Escaláveis: não exigem polling - as notificações são enviadas apenas quando os eventos acontecem

Visão geral

Cada canal do Echobell pode ser configurado com uma URL de webhook exclusiva. Quando essa URL é chamada, o canal envia notificações para todos os seus inscritos, com base nos modelos de notificação configurados e nas variáveis fornecidas.

Formato da URL do webhook

https://hook.echobell.one/t/{channel-token}

Você encontra a URL de webhook do seu canal na tela de detalhes do canal, no app Echobell.

Fazendo requisições de webhook

Os webhooks do Echobell aceitam tanto o método GET quanto o POST:

Requisição GET

Você pode passar variáveis por parâmetros de query:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

Requisição POST

Para requisições POST, envie as variáveis em um corpo JSON:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

Somente POST

Cada canal tem uma chave Somente POST em Configurações avançadas no app Echobell. Ela vem desativada por padrão.

Quando está ativada, apenas POST pode acionar o canal. Um GET para a URL do webhook é rejeitado com 405 Method Not Allowed, e nenhuma notificação é enviada:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

Requisições HEAD não são afetadas — elas respondem 200 e nunca acionam uma notificação, com Somente POST ativado ou desativado.

Ative a opção quando a URL do webhook for parar em algum lugar que busca links automaticamente — uma mensagem de chat, uma página de wiki, a barra de endereços do navegador — para que visualizar ou abrir a URL não dispare um alerta. Deixe desativada se algum dos seus chamadores aciona o canal com GET.

Variáveis especiais

O Echobell oferece uma variável especial que adiciona funcionalidades às suas notificações:

externalLink: quando incluída na requisição, cria um link clicável na tela de registros de notificação. Útil para apontar para informações detalhadas ou recursos relacionados.

Exemplo com link externo:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Variáveis de modelo

As variáveis passadas por webhooks podem ser usadas nos seus modelos de notificação com a sintaxe {{variableName}}:

Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%

Quando acionados, esses modelos são preenchidos com os valores fornecidos na sua requisição de webhook.

Variáveis de hora do sistema (UTC)

Além dos dados que você envia, o Echobell oferece variáveis de hora do sistema somente leitura, sempre disponíveis nos modelos e nas condições. Todos os valores são calculados em UTC. Os campos planos incluem date, time, year, month, dayOfWeek, hour, minute e second. Outros — como sys.dayOfWeekName, sys.epochMs e sys.epochSeconds — estão disponíveis apenas no namespace sys.. Consulte Condições para ver a lista completa e exemplos.

Casos de uso comuns

Os webhooks são o método de gatilho mais popular no Echobell e são especialmente úteis para:

DevOps e monitoramento

Monitoramento de servidores: alertas de CPU, memória e uso de disco vindos de sistemas de monitoramento como Prometheus ou Grafana
Monitoramento de uptime: alertas de disponibilidade de sites e serviços vindos do Uptime Kuma ou do UptimeRobot
Monitoramento de containers: falhas de pods do Docker e do Kubernetes e limitações de recursos
Agregação de logs: erros e exceções críticos vindos de sistemas de gerenciamento de logs

Desenvolvimento e CI/CD

Notificações de build: builds com falha, resultados de testes e status de deploy vindos do GitHub Actions ou do GitLab CI
Qualidade de código: erros de lint, vulnerabilidades de segurança e mudanças na cobertura de testes
Eventos de repositório: pull requests, commits, releases e atividade dos colaboradores
Acompanhamento de deploys: deploys bem-sucedidos, rollbacks e mudanças de ambiente

Aplicações de negócio

E-commerce: novos pedidos, confirmações de pagamento, avisos de estoque e atualizações de envio
CRM: novos leads, negócios fechados, chamados de suporte e interações com clientes
Processamento de pagamentos: transações concluídas, pedidos de reembolso e alertas de fraude
Envios de formulário: formulários de contato, respostas de pesquisas e cadastros concluídos

IoT e casa inteligente

Eventos de casa inteligente: sensores de porta, detecção de movimento e mudanças de temperatura via Home Assistant
Dispositivos IoT: leituras de sensores, mudanças de status dos dispositivos e problemas de conectividade
Sistemas de segurança: disparos de alarme, detecção de movimento por câmera e eventos de controle de acesso
Monitoramento ambiental: limites de temperatura, umidade e qualidade do ar ultrapassados

Trading e finanças

Alertas de mercado: movimentos de preço e indicadores técnicos do TradingView
Monitoramento de carteira: mudanças de posição, chamadas de margem e saldos das contas
Eventos econômicos: divulgação de notícias, relatórios de resultados e mudanças no sentimento do mercado

Consulte nossos guias de integração para ver instruções de configuração específicas das plataformas mais populares.

Boas práticas

Tratamento de erros

Não confie apenas no status HTTP — sempre inspecione o corpo JSON da resposta e verifique o campo success:

200 OK: a requisição foi recebida. Confira o corpo JSON: success: true significa que o canal foi acionado, enquanto success: false significa que a requisição foi aceita, mas nenhuma notificação foi enviada (por exemplo, um token de canal desconhecido, que ainda assim retorna HTTP 200).
400 Bad Request: o token do canal tem o comprimento errado. Corrija a URL do webhook.
405 Method Not Allowed: o canal está com Somente POST ativado e a requisição não era um POST. Mude o chamador para POST ou desative a configuração.
500 Server Error: problema temporário; tente de novo com backoff exponencial

O Echobell não aplica limite de taxa às chamadas de webhook, então não existe resposta 429. Como um token desconhecido (mas com o comprimento correto) ainda retorna 200 com success: false, decida sempre com base no campo success do JSON, e não no status HTTP.

Limitação de taxa

Implemente intervalos razoáveis entre as chamadas de webhook para não sobrecarregar seu sistema de notificações:

Para monitoramento contínuo, agrupe vários eventos em uma única notificação
Use condições para filtrar eventos não críticos
Considere agregar eventos disparados em sequência rápida (por exemplo, vários erros em pouco tempo)
Evite enviar gatilhos duplicados em sequência rápida, para manter a confiabilidade dos alertas críticos

Segurança dos dados

Compartilhe as URLs de webhook apenas com sistemas e serviços confiáveis:

Trate as URLs de webhook como segredos - elas dão acesso direto para enviar notificações
Não faça commit de URLs de webhook em repositórios públicos nem as compartilhe em documentação pública
Troque as URLs de webhook periodicamente ou quando alguém sair do time
Use o recurso "Redefinir token" do canal para invalidar URLs antigas em caso de comprometimento
Considere usar variáveis de ambiente ou sistemas de gerenciamento de segredos para armazenar as URLs

Nomes de variáveis

Use nomes de variáveis claros e consistentes nas suas chamadas de webhook:

Use nomes descritivos: server_name em vez de s ou srv
Siga uma convenção de nomes consistente entre os canais
Documente quais variáveis os seus modelos esperam
Verifique se todas as variáveis obrigatórias estão presentes antes de enviar

Testes

Teste a fundo sua integração de webhook antes de colocá-la em produção:

Use ferramentas como curl, o Postman ou o cliente HTTP da sua linguagem para os primeiros testes
Comece com modelos simples e vá aumentando a complexidade aos poucos
Teste os métodos GET e POST para descobrir qual funciona melhor
Verifique se caracteres especiais e Unicode são tratados corretamente
Teste cenários de erro (variáveis ausentes, JSON malformado) para entender o comportamento
Use canais de teste separados dos canais de produção durante o desenvolvimento

Design dos modelos

Crie modelos que continuem úteis mesmo quando variáveis opcionais estiverem ausentes:

Ofereça valores padrão ou alternativos para os dados opcionais
Estruture os modelos para lidar bem com variáveis ausentes
Teste os modelos com várias combinações de variáveis presentes e ausentes
Use expressões condicionais para trechos opcionais

Monitoramento

Monitore suas integrações de webhook para garantir que estão funcionando corretamente:

Registre em log as chamadas de webhook bem-sucedidas e as que falharam na sua aplicação
Acompanhe as taxas de entrega das notificações e os tempos de resposta
Configure alertas para erros de webhook ou padrões incomuns
Revise e teste periodicamente as integrações de webhook críticas

Privacidade e segurança

Entenda como o Echobell trata os dados dos seus webhooks:

O que é armazenado

Nos nossos servidores:
- URLs de webhook (tokens) - necessárias para rotear as requisições recebidas até os canais
- Configurações dos canais - modelos, condições, ajustes
- Relações de inscrição - quais usuários se inscrevem em quais canais
No seu dispositivo:
- Conteúdo da notificação - o título e o corpo renderizados
- Histórico de acionamentos - quando as notificações foram recebidas
- Valores das variáveis - os dados passados nas chamadas de webhook
- Links e metadados - externalLink e outros dados associados

O que não é armazenado

Não armazenamos permanentemente os payloads brutos dos webhooks
Não registramos nem retemos dados sensíveis das suas requisições
Não analisamos nem processamos o conteúdo das notificações para nenhuma finalidade
Não compartilhamos os dados dos seus webhooks com terceiros

Recomendações de segurança

Trate as URLs de webhook como chaves de API - elas dão acesso, sem autenticação, para enviar notificações
Troque as URLs com frequência - use o recurso "Redefinir token" para gerar novas URLs
Use clientes HTTPS - embora aceitemos apenas conexões HTTPS, garanta que seu cliente valide os certificados
Valide a origem dos webhooks - se possível, restrinja quais IPs ou serviços podem chamar seus webhooks
Monitore abusos - fique de olho em padrões incomuns ou usos não autorizados
Separe os ambientes - use canais diferentes para desenvolvimento, homologação e produção

Saiba mais na nossa documentação de suporte.

Solução de problemas

Se seus webhooks não estiverem funcionando como esperado, tente estes passos de diagnóstico:

O webhook não aciona notificações

Verifique se a URL do webhook está correta
- Copie a URL diretamente do app Echobell
- Confirme que não foram adicionados espaços ou caracteres extras
- Verifique se você está usando https://hook.echobell.one/t/ e nenhum outro domínio
Verifique se o canal está ativo
- Abra o canal no app Echobell
- Confirme que ele não foi excluído nem arquivado
- Confirme que você não redefiniu o token do webhook (o que invalidaria a URL)
Garanta que seu payload JSON está formatado corretamente (para requisições POST)
- Use um validador de JSON para conferir seu payload
- Verifique se as strings estão entre aspas
- Confirme que o cabeçalho Content-Type está definido como application/json
Confirme que todas as variáveis obrigatórias dos seus modelos estão sendo fornecidas
- Confira seus modelos de notificação para ver quais variáveis eles usam
- Verifique se essas variáveis estão na requisição do webhook (parâmetros de query ou corpo JSON)
- Lembre-se de que variáveis ausentes são renderizadas como strings vazias
Verifique se o canal tem inscritos ativos
- As notificações só são enviadas se alguém estiver inscrito no canal
- Confirme sua inscrição na lista de canais do app
- Verifique se as inscrições não foram removidas sem querer

Notificações renderizadas incorretamente

Os nomes das variáveis não coincidem
- O modelo usa {{server_name}}, mas o webhook envia serverName
- Os nomes das variáveis diferenciam maiúsculas de minúsculas e precisam coincidir exatamente
- Verifique se há erros de digitação nos nomes das variáveis
Dados aninhados inacessíveis
- Use a notação de ponto: {{user.name}} ou a notação de colchetes: {{user["name"]}}
- Verifique se a estrutura do seu JSON corresponde ao que o modelo espera
- Teste primeiro com variáveis simples e planas e só depois adicione aninhamento
Caracteres especiais causando problemas
- Codifique corretamente os parâmetros de query na URL
- Faça o escape dos caracteres especiais do JSON nos corpos das requisições POST
- Teste primeiro com texto ASCII simples

Testando sua integração

Use o curl para testar seu webhook diretamente:

# Test with query parameters
curl "https://hook.echobell.one/t/<channel-token>?test=hello&status=working"

# Test with JSON body
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"test": "hello", "status": "working"}'

Você deve receber uma notificação imediatamente se tudo estiver configurado corretamente.

Ainda com problemas?

Se você já tentou os passos acima e continua enfrentando problemas:

Acesse nossa Central de suporte para ver mais guias de solução de problemas
Verifique se há problemas conhecidos ou atualizações sobre o status do serviço
Entre em contato pelo e-mail echobell@weelone.com com:
- Uma descrição do problema
- Os passos que você já tentou
- Um exemplo de URL do webhook (com o token removido/ocultado)
- Um exemplo do payload da requisição
- O comportamento esperado e o comportamento observado

Próximos passos

Agora que você entende a integração com webhooks:

Aprenda a sintaxe dos modelos - crie notificações dinâmicas e informativas
Use condições - filtre notificações com base nos dados
Explore as integrações - conecte-se às ferramentas que você já usa
Configure alertas do Grafana - monitore a sua infraestrutura
Configure o GitHub Actions - receba notificações de CI/CD
Gatilhos por e-mail - método de gatilho alternativo para sistemas baseados em e-mail

Pronto para integrar o Echobell aos seus sistemas? Crie seu primeiro canal e comece a receber notificações instantâneas!