Ir al contenido

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.

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.

Ventana de terminal
curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/test \
-H "Authorization: Bearer $MESSAJO_API_KEY"

La prueba va solo a ese destino, en un único intento, incluso si está pausado.

  • Destino pausado, por ti o por la pausa automática (auto_paused). Cada evento nuevo se vuelve una entrega failed con destination_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, como org.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: 400 destination_url_not_allowed. No se aceptan redes privadas, http ni hosts inválidos. Usa una URL https pública; details[].message dice el motivo.

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.

Las cinco causas de Errores comunes:

  1. JSON re-serializado: firma el cuerpo crudo, nunca JSON.stringify(req.body).
  2. Reloj fuera de la tolerancia de 5 minutos: sincroniza el servidor (NTP).
  3. Espacio o salto de línea al final del secreto (común en .env).
  4. Secreto sin el prefijo: la clave es el secreto entero, con whsec_.
  5. 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.

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.

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 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.

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).

Ventana de terminal
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" }'

La respuesta es { queued, has_more }. Las entregas y los eventos se guardan por 30 días. Consulta Lista de fallos y reenvío.

Si tu proceso no tiene URL pública (script, escritorio, entorno local), consulta el destino WebSocket.