Telm puede enviar eventos de moderación a tu servidor en tiempo real. Registras un endpoint, eliges qué eventos recibir, y Telm envía un POST firmado por cada uno. Cada entrega lleva una firma HMAC-SHA256 que verificas con el secreto de tu endpoint. Las entregas fallidas se reintentan según una programación; un endpoint permanentemente inalcanzable se desactiva automáticamente.
1El sobre del evento
Cada webhook es un HTTP POST con un cuerpo JSON en un sobre común. El sobre tiene un id (un identificador de entrega único para la deduplicación), un type (el nombre del evento), una marca de tiempo created_at, el group_id al que pertenece el evento, y un objeto data cuya forma depende del tipo de evento.
El id es determinista para los eventos reales, así que si el mismo evento se entrega dos veces (por ejemplo tras un reintento) recibes el mismo id ambas veces. Usa el encabezado X-Telm-Delivery (que refleja este id) como clave de idempotencia para que tu manejador procese cada evento solo una vez.
- Campos del sobre: id, type, created_at, group_id, data.
- type es uno de los nombres de evento del catálogo de abajo.
- data lleva los campos específicos del evento.
- Usa id (y el encabezado X-Telm-Delivery) para deduplicar los reintentos.
2Catálogo de eventos
Suscribes un endpoint a cualquier subconjunto del catálogo. spam.detected se activa cuando el motor marca un mensaje como spam. message.suspicious se activa en modo de monitorización, cuando el motor habría actuado pero solo puntuó el mensaje en la sombra. Los eventos de miembro cubren a las personas que entran, salen y son castigadas.
El evento ping es especial: no forma parte del catálogo suscribible y solo se envía cuando activas una entrega de prueba para un endpoint, para que puedas confirmar que tu receptor y tu comprobación de firma funcionan de extremo a extremo.
- spam.detected — un mensaje fue clasificado como spam.
- message.suspicious — una detección en la sombra (modo de monitorización).
- user.banned, user.kicked, user.muted — se aplicó una acción de moderación.
- user.joined, user.left — un miembro entró o salió del grupo.
- ping — un evento de prueba manual, nunca activado por actividad real.
3Campos de carga útil por evento
Para spam.detected y message.suspicious, el objeto data lleva message_id, user_id, username, el texto del mensaje (truncado para mensajes muy largos), la acción tomada, una category, una reason, el idioma detectado, y una puntuación de confidence. message.suspicious lleva además la puntuación de sombra.
Para los eventos de miembro (user.joined, user.left, user.banned, user.kicked, user.muted), el objeto data lleva user_id, username, first_name, un message_id opcional, y una reason donde aplique. Un evento subyacente puede producir más de un webhook: un mensaje de spam que desencadena un baneo se entrega como spam.detected y user.banned a la vez.
- Eventos de spam: message_id, user_id, username, text, action, category, reason, language, confidence (más score para message.suspicious).
- Eventos de miembro: user_id, username, first_name, message_id, reason.
- Un solo incidente puede emitir varios eventos; correlaciónalos por user_id y group_id.
4Verificar la firma HMAC
Cada entrega está firmada para que puedas estar seguro de que realmente vino de Telm y no fue manipulada. Obtienes un secreto de endpoint (empieza por whsec_) una vez, cuando creas el endpoint. Guárdalo y úsalo para verificar cada petición entrante.
Para verificar, toma el valor del encabezado X-Telm-Timestamp, añade un punto, luego añade el cuerpo bruto exacto de la petición, y calcula un HMAC-SHA256 de esa cadena usando el secreto de tu endpoint como clave. Codifica el resultado en hexadecimal y anteponle v1=: debe ser igual al encabezado X-Telm-Signature. Compáralo con una comparación de tiempo constante, y rechaza la petición si la marca de tiempo tiene más de unos minutos (cinco es un buen corte) para bloquear las repeticiones.
- X-Telm-Event — el tipo de evento.
- X-Telm-Delivery — el id de entrega (clave de idempotencia).
- X-Telm-Timestamp — segundos unix, firmados para prevenir repeticiones.
- X-Telm-Signature — v1= más el HMAC-SHA256 en hexadecimal de la marca de tiempo, un punto, y el cuerpo bruto.
5Entrega, reintentos y desactivación automática
Una entrega cuenta como exitosa solo si tu endpoint responde con un estado 2xx. Cualquier otra cosa (un código que no sea 2xx, un tiempo de espera agotado, o un error de conexión) se trata como un fallo y se reintenta según una programación fija: de inmediato, luego tras 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas, en seis intentos que abarcan aproximadamente ocho horas y media antes de que la entrega se cierre como fallida.
Si un endpoint sigue fallando (al menos veinte fallos consecutivos sin ninguna entrega exitosa durante tres días) Telm lo desactiva automáticamente para que deje de enviar a una URL muerta. Puedes reactivarlo desde el panel una vez que tu receptor vuelve a estar sano.
- Éxito = HTTP 2xx. Responde rápido (en unos diez segundos) y haz el trabajo pesado de forma asíncrona.
- Programación de reintentos: inmediato, +1m, +5m, +30m, +2h, +6h (seis intentos).
- Desactivado automáticamente tras 20 fallos seguidos sin ningún éxito en 72 horas.
- Registrar webhooks requiere el plan Pro o superior.