Webhooks — eventos de moderação em tempo real nos seus sistemas

1O que os webhooks fazem

Em vez de fazer polling na API, você registra uma URL e o Telm envia um HTTP POST assinado para ela sempre que algo acontece no seu grupo. É assim que você leva os eventos de moderação para os seus próprios sistemas — um painel, um data warehouse, um canal de alertas — em tempo real.

Você gerencia os endpoints de webhook pela API: registra uma URL, escolhe quais eventos assinar, opcionalmente os limita a grupos específicos, envia um ping de teste e lê o registro recente de entregas.

2Por que o envio supera o polling

Você poderia chamar o endpoint do diário em um temporizador para encontrar novos eventos, mas isso adiciona latência, gasta cota e pode perder o momento exato em que algo acontece. Os webhooks invertem o modelo: o Telm avisa você no instante em que um evento dispara, então os seus sistemas reagem em segundos.

Usos típicos incluem espelhar banimentos nas suas próprias ferramentas de administração, alertar um canal da equipe quando um ataque é detectado, transmitir detecções para análises ou disparar um fluxo de trabalho quando um membro entra ou sai.

• Tempo real: você fica sabendo de um evento assim que ele acontece, não no seu próximo polling.
• Eficiente: sem leituras repetidas que consomem sua cota diária.
• Completo: as entregas são repetidas, então uma breve indisponibilidade do seu lado não perde eventos.

3Eventos que você pode assinar

Existem sete tipos de eventos assináveis, cobrindo veredictos de spam, punições e mudanças de participação. Uma única mensagem moderada pode produzir mais de um evento — uma mensagem de spam que termina em banimento emite tanto spam.detected quanto user.banned.

• spam.detected — o motor sinalizou uma mensagem como spam.
• message.suspicious — uma detecção sombra (modo de monitoramento) com uma pontuação.
• user.banned — um membro foi banido.
• user.kicked — um membro foi removido.
• user.muted — um membro foi silenciado.
• user.joined — um membro entrou no grupo.
• user.left — um membro saiu do grupo.

4O envelope do payload

Cada entrega é um envelope JSON com um pequeno conjunto estável de campos de nível superior e um objeto data específico do evento por dentro. Você pode rotear pelo tipo e pelo horário sem analisar os detalhes até precisar deles.

• id — um id de entrega único; reentregas do mesmo evento reutilizam o mesmo id, e é assim que você deduplica.
• type — o tipo do evento, um dos sete acima.
• created_at — quando o evento disparou, em UTC no formato RFC3339.
• group_id — o grupo ao qual o evento pertence (quando aplicável).
• data — um objeto específico do evento: detalhes da mensagem e do veredito para eventos de spam, detalhes do membro para eventos de participação.

5Verificando que as entregas são realmente do Telm

Cada entrega é assinada para que o seu servidor possa confirmar que a requisição veio genuinamente do Telm e não foi adulterada no caminho. Valide a assinatura antes de confiar no payload e rejeite qualquer coisa que não corresponda.

A assinatura é um HMAC-SHA256 do timestamp e do corpo bruto da requisição, com chave no segredo de assinatura do seu endpoint. Para verificar, recalcule o HMAC sobre o cabeçalho de timestamp e os bytes exatos que você recebeu, e compare-o com o cabeçalho de assinatura.

• X-Telm-Signature — a assinatura, formatada como v1 seguido do HMAC-SHA256 em hex do timestamp unido ao corpo.
• X-Telm-Timestamp — o timestamp em segundos unix que é assinado, para que você possa rejeitar entregas antigas ou repetidas.
• X-Telm-Event — o tipo do evento, e X-Telm-Delivery — o id de entrega para deduplicação.
• O segredo de assinatura é mostrado uma vez quando você cria o endpoint e começa com whsec_. Guarde-o com segurança; é a única coisa que prova que uma entrega é genuína.

6Entrega confiável e deduplicada

A entrega é ao-menos-uma-vez: o Telm garante que um evento chegue até você, o que significa que o mesmo evento pode, ocasionalmente, chegar duas vezes. Como cada reentrega reutiliza o mesmo id de entrega, você elimina duplicatas armazenando os ids já processados e ignorando as repetições.

Se o seu endpoint estiver inacessível ou retornar um erro, a entrega é repetida em um cronograma fixo — aproximadamente após um minuto, cinco minutos, trinta minutos, duas horas e seis horas, até seis tentativas ao longo de cerca de oito horas e meia. Um endpoint que continua falhando é desativado automaticamente para proteger os dois lados, e o proprietário é notificado.

• Responda rapidamente com um status 2xx; faça o trabalho pesado de forma assíncrona depois de confirmar.
• Deduplique pelo id de entrega — nunca pelo conteúdo do payload.
• Um endpoint que falha cerca de vinte vezes seguidas sem nenhum sucesso dentro de uma janela de 72 horas é desativado automaticamente; reative-o quando o seu servidor estiver saudável.

7Gerenciando endpoints e lendo o registro

Você registra, edita e remove endpoints de webhook pela API. Quando cria um, você recebe o segredo de assinatura exatamente uma vez, escolhe os eventos a assinar e opcionalmente o limita a grupos específicos. Uma chamada de teste envia um ping assinado para que você confirme que a sua verificação funciona antes que o tráfego real comece.

Cada endpoint mantém um registro de entregas que você pode consultar para ver o que foi enviado, quando e se teve sucesso — útil para depurar um receptor sem esperar o próximo evento ao vivo.

• Crie um endpoint e copie o segredo whsec_ imediatamente.
• Envie um ping de teste para validar a sua verificação de assinatura de ponta a ponta.
• Limite um endpoint a um grupo ou deixe-o aberto a todos os grupos que você administra.
• Leia o registro de entregas para inspecionar as tentativas recentes e os seus resultados.

8Boas práticas e erros comuns

Um receptor robusto segue algumas regras que evitam os problemas mais comuns.

• Verifique a assinatura sobre os bytes brutos do corpo — analisar para JSON primeiro e reserializar pode mudar os bytes e quebrar a verificação.
• Retorne 2xx rapidamente e processe depois; um handler lento causa timeouts e repetições desnecessárias.
• Torne o tratamento idempotente para que um evento reentregue não seja contado em dobro.
• Use HTTPS em uma URL publicamente acessível; o Telm bloqueia endereços internos e privados e não segue redirecionamentos.
• Mantenha o segredo whsec_ fora de logs e do código do cliente.