📘 Guía de Respuestas y Errores de Webhooks en Atom

🚀 Conceptos Básicos

Los Webhooks funcionan como "puertas de entrada" que permiten a sistemas externos (como tu CRM o tu sitio web) indicarle a Atom que envíe un mensaje automático a un cliente.

Al recibir una petición, Atom emite una respuesta inmediata mediante un código de estado numérico. Que Atom reciba el mensaje con éxito significa que la orden fue aceptada por el sistema; sin embargo, la entrega final al dispositivo del cliente dependerá de que los datos sean válidos y de las políticas vigentes de WhatsApp.

1. Webhooks Estándar (Integraciones Propias)

Si utilizas un sistema propio u otro software directo, el Webhook se ejecuta de forma inmediata y el servidor devolverá los siguientes códigos HTTP:

Código HTTP	Significado	Detalles y Solución
200 ✅	Ejecutado con éxito	Atom recibió la información y el flujo se ejecutó correctamente.
400 ⚠️	Datos incorrectos o faltantes	Puede faltar el ID del Webhook, el ID de tu empresa (`CompanyId`), la información del canal o parámetros obligatorios requeridos por tu flujo.
401 🔐	Error de seguridad (Token)	Falta el token de autorización, el formato no es válido (debe ser tipo Bearer) o el token no corresponde a la empresa del Webhook.
403 🚫	Webhook bloqueado	El Webhook está inactivo o se ha deshabilitado por seguridad tras alcanzar un umbral crítico de 1,000 errores consecutivos.
404 🔍	No encontrado	El Webhook, el canal o la empresa a la que intentas llamar no existe en el sistema o fue eliminada.
500 🛠️	Error interno	Ocurrió un fallo inesperado en los servidores de Atom. Intenta de nuevo más tarde.

2. Webhooks con HubSpot (Procesamiento Asíncrono)

La Regla del Código 202

HubSpot impone límites estrictos en la cantidad de peticiones permitidas por segundo (Rate Limits). Para cumplir con esta regla y evitar bloqueos, Atom procesa estas peticiones en una fila de espera asíncrona.

Por esta razón, cuando envías un Webhook desde HubSpot, Atom siempre devolverá de entrada un código 202 (Aceptado).

💡 Tip: El código 202 funciona como la confirmación de toma de pedido. Para conocer el resultado real del procesamiento, debes inspeccionar la respuesta JSON devuelta dentro del objeto de salida.

Lectura de la Respuesta JSON

Dentro del cuerpo de la respuesta con código 202, visualizarás la siguiente estructura de datos:

JSON

{
  "message": "...",
  "hasErrors": true,
  "outputFields": {
    "success": false,
    "httpStatus": 404,
    "errorCode": "GEN_REQ_WEBHOOK_ERROR_002",
    "errorMessage": "..."
  }
}

hasErrors: Si es true, indica que ocurrió un problema durante el proceso.
success: Si es false, la petición no se pudo procesar exitosamente.
httpStatus: Muestra el código de error HTTP real (por ejemplo, 404 para "no encontrado").
errorCode: Código único del error utilizado para identificar la causa específica en las tablas de referencia.

🔍 Diccionario Completo de Errores (HubSpot)

📱 Contacto y Teléfono

Código de Error	Significado
`GEN_REQ_PHONE_001`	Falta el teléfono. No se envió un número de contacto.
`GEN_REQ_PHONE_002`	Teléfono inválido. El número no tiene el formato correcto para WhatsApp.
`GEN_REQ_WEBHOOK_ERROR_006`	Falta el identificador del webhook o el número de teléfono en la petición.

⚙️ Configuración del Flujo y Canal

Código de Error	Significado
`GEN_REQ_WEBHOOK_ERROR_002`	Webhook no encontrado (revisa la URL enviada).
`GEN_REQ_WEBHOOK_ERROR_003`	Webhook no registrado en el sistema.
`GEN_REQ_WEBHOOK_ERROR_004`	Webhook inactivo o deshabilitado.
`GEN_REQ_WEBHOOK_ERROR_005`	ID del Webhook inválido.
`GEN_REQ_WEBHOOK_ERROR_007`	Faltan parámetros obligatorios en la petición.
`GEN_REQ_COMPANY_009`	Falta el ID de la empresa (`Company ID`).
`GEN_REQ_CHANNEL_003`	Canal no encontrado. La línea de WhatsApp no existe o está desconectada.
`GEN_REQ_CHANNEL_004`	El canal no tiene un `App ID` asociado.
`GEN_REQ_TEMPLATE_005`	Plantilla no encontrada. La plantilla ya no existe.
`GEN_REQ_TEMPLATE_006`	Datos de plantilla inválidos. Variables mal mapeadas.
`GEN_REQ_ACTION_001`	Acción de inicio de flujo no encontrada.

🔐 Seguridad y Credenciales

Código de Error	Significado
`GEN_REQ_AUTHORIZATION_TOKEN_001`	Falta el token de autorización.
`GEN_REQ_AUTHORIZATION_TOKEN_002`	Formato de token inválido.
`GEN_REQ_AUTHORIZATION_TOKEN_003`	El token enviado no corresponde a tu cuenta.
`GEN_REQ_CRED_007`	Credenciales no encontradas.
`GEN_REQ_INT_008`	Integración no encontrada.

👨‍💻 Agentes y Asignaciones

Código de Error	Significado
`GEN_REQ_AGENT_001`	Agente de flujo no encontrado.
`GEN_REQ_AGENT_002`	Agente de flujo inactivo.
`GEN_REQ_APPID_001`	`App ID` del agente no encontrado.

⚠️ Sistema y Errores Críticos

Código de Error	Significado
`GEN_REQ_TOO_MANY_ERRORS_001`	Bloqueo Automático. Exceso de errores previos acumulados (umbral alcanzado).
`GEN_REQ_WEBHOOK_ERROR_008`	Falló la creación de la tarea en la fila de espera asíncrona.
`GEN_NOT_FOUND_010`	Recurso de soporte o entidad no soportada.
`GEN_NOT_FOUND_011`	Entidad no encontrada.
`INT_HS_WORKFLOW_002`	Error al enviar la plantilla desde el Workflow de HubSpot.
`GEN_REQ_WEBHOOK_ERROR_001`	Error inesperado del sistema (Fallback).

📩 Recepción de Eventos (`POST /hubspot/webhook`)

Código HTTP	Significado
200 ✅	Eventos procesados correctamente.
400 ⚠️	El formato enviado no es una lista de eventos válida.

💡 Consejos para el Éxito

Sigue estas recomendaciones técnicas para garantizar el correcto envío de tus comunicaciones:

El teléfono es la llave: Incluye siempre el código de país (ejemplo: 521...) según el formato requerido por WhatsApp.
Estado "Publicado": Los Webhooks solo funcionan si el flujo conversacional se encuentra en estado Publicado. Los flujos en borrador se ignoran.
Conversaciones con Agentes: Si mantienes activa la "exclusión por agente", el mensaje automático no se enviará si el cliente se encuentra hablando con un asesor humano.
Mapeo de Variables: Revisa que los nombres de los campos enviados por tu sistema coincidan de forma exacta con los nombres de las variables configuradas en Atom.

⚠️ Importante: Si necesitas asistencia técnica con nuestro equipo de soporte, comparte siempre el valor de errorCode para acelerar el tiempo de respuesta y diagnóstico.

Dominar los códigos de respuesta y el diccionario de errores te permite diagnosticar integraciones en tiempo récord y mantener tus automatizaciones operando sin interrupciones. ¡Toma el control de tus Webhooks y escala tus flujos con total confianza! ✅