Webhooks — eventos de moderación en tiempo real en tus sistemas

1Qué hacen los webhooks

En lugar de sondear la API, registras una URL y Telm le envía un HTTP POST firmado cada vez que algo ocurre en tu grupo. Así es como llevas los eventos de moderación a tus propios sistemas —un panel, un data warehouse, un canal de alertas— en tiempo real.

Gestionas los endpoints de webhook a través de la API: registra una URL, elige a qué eventos suscribirte, opcionalmente limítalos a grupos concretos, envía un ping de prueba y lee el registro de entregas reciente.

2Por qué el push gana al sondeo

Podrías llamar al endpoint del registro con un temporizador para encontrar eventos nuevos, pero eso añade latencia, gasta cuota y puede perderse el momento exacto en que algo ocurre. Los webhooks invierten el modelo: Telm te avisa en el instante en que se dispara un evento, así que tus sistemas reaccionan en segundos.

Los usos típicos incluyen reflejar los baneos en tus propias herramientas de administración, alertar a un canal del equipo cuando se detecta un raid, transmitir las detecciones a las analíticas, o disparar un flujo de trabajo cuando un miembro entra o sale.

• Tiempo real: te enteras de un evento cuando ocurre, no en tu siguiente sondeo.
• Eficiente: sin lecturas repetidas que consuman tu cuota diaria.
• Completo: las entregas se reintentan, así que una breve caída de tu lado no pierde eventos.

3Eventos a los que puedes suscribirte

Hay siete tipos de evento a los que suscribirse, que cubren los veredictos de spam, las sanciones y los cambios de membresía. Un único mensaje moderado puede producir más de un evento: un mensaje de spam que termina en un baneo emite tanto spam.detected como user.banned.

• spam.detected — el motor marcó un mensaje como spam.
• message.suspicious — una detección en la sombra (modo de monitorización) con una puntuación.
• user.banned — se baneó a un miembro.
• user.kicked — se expulsó a un miembro.
• user.muted — se silenció a un miembro.
• user.joined — un miembro se unió al grupo.
• user.left — un miembro salió del grupo.

4La envoltura del payload

Cada entrega es una envoltura JSON con un conjunto pequeño y estable de campos de nivel superior y un objeto data específico del evento en su interior. Puedes enrutar por el tipo y la hora sin analizar los detalles hasta que los necesites.

• id — un id de entrega único; las reentregas del mismo evento reutilizan el mismo id, que es como deduplicas.
• type — el tipo de evento, uno de los siete anteriores.
• created_at — cuándo se disparó el evento, en RFC3339 UTC.
• group_id — el grupo al que pertenece el evento (cuando corresponde).
• data — un objeto específico del evento: detalles del mensaje y del veredicto para los eventos de spam, detalles del miembro para los eventos de membresía.

5Verificar que las entregas son realmente de Telm

Cada entrega se firma para que tu servidor pueda confirmar que la petición vino realmente de Telm y no se manipuló en tránsito. Valida la firma antes de confiar en el payload, y rechaza todo lo que no coincida.

La firma es un HMAC-SHA256 de la marca de tiempo y el cuerpo de la petición en bruto, con la clave de tu secreto de firma del endpoint. Para verificar, recalcula el HMAC sobre la cabecera de marca de tiempo y los bytes exactos que recibiste, y compáralo con la cabecera de firma.

• X-Telm-Signature — la firma, con formato v1 seguido del HMAC-SHA256 en hexadecimal de la marca de tiempo unida al cuerpo.
• X-Telm-Timestamp — la marca de tiempo en segundos unix que se firma, para que puedas rechazar entregas obsoletas o reproducidas.
• X-Telm-Event — el tipo de evento, y X-Telm-Delivery — el id de entrega para la deduplicación.
• El secreto de firma se muestra una vez cuando creas el endpoint y empieza por whsec_. Guárdalo de forma segura; es lo único que demuestra que una entrega es genuina.

6Entrega fiable y deduplicada

La entrega es al-menos-una-vez: Telm se asegura de que un evento te llegue, lo que significa que el mismo evento puede llegar ocasionalmente dos veces. Como cada reentrega reutiliza el mismo id de entrega, deduplicas almacenando los id que ya has procesado y omitiendo las repeticiones.

Si tu endpoint no está accesible o devuelve un error, la entrega se reintenta según un calendario fijo —aproximadamente al minuto, a los cinco minutos, a los treinta minutos, a las dos horas y a las seis horas—, hasta seis intentos a lo largo de unas ocho horas y media. Un endpoint que sigue fallando se desactiva automáticamente para proteger a ambas partes, y se avisa al propietario.

• Responde rápido con un estado 2xx; haz el trabajo pesado de forma asíncrona después de confirmar.
• Deduplica por el id de entrega, nunca por el contenido del payload.
• Un endpoint que falla unas veinte veces seguidas sin ningún éxito dentro de una ventana de 72 horas se desactiva automáticamente; reactívalo cuando tu servidor esté sano.

7Gestionar endpoints y leer el registro

Registras, editas y eliminas los endpoints de webhook a través de la API. Cuando creas uno recibes el secreto de firma exactamente una vez, eliges los eventos a los que suscribirte y opcionalmente lo limitas a grupos concretos. Una llamada de prueba envía un ping firmado para que confirmes que tu verificación funciona antes de que empiece el tráfico real.

Cada endpoint conserva un registro de entregas que puedes consultar para ver qué se envió, cuándo y si tuvo éxito — útil para depurar un receptor sin esperar al próximo evento en vivo.

• Crea un endpoint y copia el secreto whsec_ de inmediato.
• Envía un ping de prueba para validar tu comprobación de firma de extremo a extremo.
• Limita un endpoint a un grupo o déjalo abierto a todos los grupos que administras.
• Lee el registro de entregas para inspeccionar los intentos recientes y sus resultados.

8Buenas prácticas y errores habituales

Un receptor robusto sigue unas pocas reglas que previenen los problemas más comunes.

• Verifica la firma sobre los bytes del cuerpo en bruto: analizar primero a JSON y volver a serializar puede cambiar los bytes y romper la comprobación.
• Devuelve 2xx rápido y procesa después; un handler lento causa timeouts y reintentos innecesarios.
• Haz que el manejo sea idempotente para que un evento reentregado no cuente dos veces.
• Usa HTTPS en una URL accesible públicamente; Telm bloquea las direcciones internas y privadas y no sigue redirecciones.
• Mantén el secreto whsec_ fuera de los registros y del código del cliente.