O Telm pode enviar eventos de moderação ao seu servidor em tempo real. Você registra um endpoint, escolhe quais eventos receber, e o Telm envia um POST assinado para cada um. Toda entrega carrega uma assinatura HMAC-SHA256 que você verifica com o segredo do seu endpoint. Entregas com falha são retentadas em um cronograma; um endpoint permanentemente inalcançável é desativado automaticamente.
1O envelope do evento
Todo webhook é um HTTP POST com um corpo JSON em um envelope comum. O envelope tem um id (um identificador único de entrega para deduplicação), um type (o nome do evento), um timestamp created_at, o group_id ao qual o evento pertence, e um objeto data cujo formato depende do tipo de evento.
O id é determinístico para eventos reais, então se o mesmo evento é entregue duas vezes — por exemplo, após uma retentativa — você recebe o mesmo id nas duas vezes. Use o cabeçalho X-Telm-Delivery (que espelha esse id) como uma chave de idempotência para que o seu handler processe cada evento apenas uma vez.
- Campos do envelope: id, type, created_at, group_id, data.
- type é um dos nomes de evento do catálogo abaixo.
- data carrega os campos específicos do evento.
- Use id (e o cabeçalho X-Telm-Delivery) para deduplicar retentativas.
2Catálogo de eventos
Você inscreve um endpoint em qualquer subconjunto do catálogo. spam.detected dispara quando o motor sinaliza uma mensagem como spam. message.suspicious dispara no modo de monitoramento, quando o motor teria agido, mas apenas pontuou a mensagem em sombra. Os eventos de membro cobrem pessoas entrando, saindo e sendo punidas.
O evento ping é especial: não faz parte do catálogo inscritível e só é enviado quando você dispara uma entrega de teste para um endpoint, para que você possa confirmar que o seu receptor e a verificação de assinatura funcionam de ponta a ponta.
- spam.detected — uma mensagem foi classificada como spam.
- message.suspicious — uma detecção em sombra (modo de monitoramento).
- user.banned, user.kicked, user.muted — uma ação de moderação foi aplicada.
- user.joined, user.left — um membro entrou ou saiu do grupo.
- ping — um evento de teste manual, nunca disparado por atividade real.
3Campos do payload por evento
Para spam.detected e message.suspicious, o objeto data carrega message_id, user_id, username, o texto da mensagem em text (truncado para mensagens muito longas), a ação em action, uma category, um reason, o idioma detectado em language e uma pontuação de confiança em confidence. message.suspicious carrega adicionalmente a pontuação em sombra em score.
Para os eventos de membro (user.joined, user.left, user.banned, user.kicked, user.muted), o objeto data carrega user_id, username, first_name, um message_id opcional e um reason onde se aplica. Um evento subjacente pode produzir mais de um webhook — uma mensagem de spam que dispara um banimento é entregue tanto como spam.detected quanto como user.banned.
- Eventos de spam: message_id, user_id, username, text, action, category, reason, language, confidence (mais score para message.suspicious).
- Eventos de membro: user_id, username, first_name, message_id, reason.
- Um único incidente pode emitir vários eventos; correlacione-os por user_id e group_id.
4Verificando a assinatura HMAC
Cada entrega é assinada para que você tenha certeza de que ela realmente veio do Telm e não foi adulterada. Você recebe um segredo de endpoint (ele começa com whsec_) uma vez, quando cria o endpoint. Guarde-o e use-o para verificar cada requisição recebida.
Para verificar, pegue o valor do cabeçalho X-Telm-Timestamp, acrescente um ponto, depois acrescente o corpo bruto exato da requisição, e calcule um HMAC-SHA256 dessa string usando o segredo do seu endpoint como chave. Codifique o resultado em hex e prefixe-o com v1= — ele deve ser igual ao cabeçalho X-Telm-Signature. Compare com uma comparação de tempo constante, e rejeite a requisição se o timestamp for mais antigo que alguns minutos (cinco é um bom corte) para bloquear repetições.
- X-Telm-Event — o tipo do evento.
- X-Telm-Delivery — o id de entrega (chave de idempotência).
- X-Telm-Timestamp — segundos unix, assinado para evitar repetições.
- X-Telm-Signature — v1= mais o HMAC-SHA256 em hex do timestamp, um ponto e o corpo bruto.
5Entrega, retentativas e desativação automática
Uma entrega conta como bem-sucedida apenas se o seu endpoint responder com um status 2xx. Qualquer outra coisa — um código não 2xx, um timeout ou um erro de conexão — é tratada como falha e retentada em um cronograma fixo: imediatamente, depois após 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas, para seis tentativas abrangendo cerca de oito horas e meia antes de a entrega ser encerrada como falha.
Se um endpoint continua falhando — pelo menos vinte falhas consecutivas sem nenhuma entrega bem-sucedida por três dias — o Telm o desativa automaticamente para que pare de enviar a uma URL morta. Você pode reativá-lo pelo painel quando o seu receptor estiver saudável de novo.
- Sucesso = HTTP 2xx. Responda rápido (em cerca de dez segundos) e faça o trabalho pesado de forma assíncrona.
- Cronograma de retentativas: imediato, +1m, +5m, +30m, +2h, +6h (seis tentativas).
- Desativado automaticamente após 20 falhas seguidas sem sucesso em 72 horas.
- Registrar webhooks requer o plano Pro ou superior.