Solución de problemas
El webhook no llega
Qué revisar cuando los eventos no llegan a tu endpoint.
Cada síntoma de abajo sigue el mismo formato: qué ves, la causa y qué hacer.
Empieza con una prueba
Sección titulada «Empieza con una prueba»Envía un evento destination.test al destino y mira el resultado. En el panel, abre las entregas del destino: cada intento guarda el estado y los primeros 1024 bytes de tu respuesta.
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/test \ -H "Authorization: Bearer $MESSAJO_API_KEY"import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY });
await messajo.destinations.test(destinationId);La prueba va solo a ese destino, en un único intento, incluso si está pausado.
No llega nada
Sección titulada «No llega nada»- Destino pausado, por ti o por la pausa automática (
auto_paused). Cada evento nuevo se vuelve una entregafailedcondestination_paused. Reanuda el destino y reenvía los fallos (abajo). - El filtro no coincide. Revisa
event_types(*,message.*o el tipo exacto) y si el destino es de una conexión o global (connection_id: null). Un destino de conexión solo recibe los eventos de ella; los eventos de organización, comoorg.standing_changed, solo llegan a destinos globales. Consulta Filtros. - Conexión que no está Activa. Revisa su estado en el panel. Si está Restringida, Desactivada o Desconectada, consulta Número restringido o bloqueado.
- URL rechazada al crear:
400destination_url_not_allowed. No se aceptan redes privadas,httpni hosts inválidos. Usa una URLhttpspública;details[].messagedice el motivo.
Llega, pero aparece como fallo
Sección titulada «Llega, pero aparece como fallo»El éxito es una respuesta 2xx en hasta 10 segundos, en total. Cualquier otra cosa cuenta como fallo: otro estado, tiempo agotado, error de red o dirección bloqueada. Una redirección (3xx) no se sigue y cuenta como fallo.
Responde 2xx rápido y procesa después, en una cola tuya. El trabajo pesado dentro de la petición agota el tiempo.
La firma no coincide
Sección titulada «La firma no coincide»Las cinco causas de Errores comunes:
- JSON re-serializado: firma el cuerpo crudo, nunca
JSON.stringify(req.body). - Reloj fuera de la tolerancia de 5 minutos: sincroniza el servidor (NTP).
- Espacio o salto de línea al final del secreto (común en
.env). - Secreto sin el prefijo: la clave es el secreto entero, con
whsec_. - Cuerpo leído con otro charset: lee los bytes como UTF-8.
Durante la rotación del secreto la cabecera trae dos valores v1, uno por secreto activo. Basta con que uno coincida.
Evento repetido o fuera de orden
Sección titulada «Evento repetido o fuera de orden»La entrega es al menos una vez. Deduplica por Messajo-Event-Id (igual al id del sobre) y, dentro de una conversación, ordena por sequence. Consulta Orden y duplicados.
Cuántas veces reintenta
Sección titulada «Cuántas veces reintenta»1 intento inmediato y 14 más, a lo largo de poco más de 23 horas: esperas de 10 s, 30 s, 1 min, 2 min, 5 min, 10 min, 20 min, 40 min, 1 h, 2 h, 3 h, 4 h, 6 h y 6 h. Cada espera varía ±10 % y ningún intento sale más de 24 horas después de crear la entrega. La tabla completa está en Reintentos y fallos.
El destino se pausó solo
Sección titulada «El destino se pausó solo»El destino se pausa cuando acumula 10 fallos seguidos y lleva fallando al menos 24 horas. Cualquier 2xx reinicia la cuenta. Al pausarse, dueños y admins reciben un correo. Detalles en Pausa automática.
Recuperar lo que quedó atrás
Sección titulada «Recuperar lo que quedó atrás»Corrige el endpoint, reanuda el destino y reenvía los fallos: Reenviar fallos en el panel, o la API con since (hasta 1000 por llamada; con has_more: true, llama de nuevo).
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/redeliver-failed \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "since": "2026-11-17T00:00:00Z" }'const { queued, has_more } = await messajo.destinations.redeliverFailed( destinationId, { since: "2026-11-17T00:00:00Z" });La respuesta es { queued, has_more }. Las entregas y los eventos se guardan por 30 días. Consulta Lista de fallos y reenvío.
Desarrollando sin URL pública
Sección titulada «Desarrollando sin URL pública»Si tu proceso no tiene URL pública (script, escritorio, entorno local), consulta el destino WebSocket.