🚀 Conceptos Básicos
¿Qué es un Webhook? Es una "puerta de entrada" que permite a sistemas externos decirle a Atom: "Oye, envíale este mensaje a este cliente ahora mismo".
Confirmación de Recepción: Cuando Atom recibe tu petición, te dará una respuesta (un código numérico). Que Atom reciba el mensaje con éxito significa que la orden fue tomada, pero la entrega final al cliente dependerá de que los datos sean correctos y de las políticas de WhatsApp.
1. Webhooks Estándar (Integraciones Propias)
Si usas un sistema propio u otro software directo, el Webhook se ejecuta de inmediato y responde con los siguientes códigos HTTP:
Código HTTP | ¿Qué significa? | Detalles y Solución |
200 ✅ | Ejecutado con éxito | Atom recibió la información y el flujo se ha ejecutado correctamente. |
400 ⚠️ | Datos Incorrectos o Faltantes | Puede faltar el ID del Webhook, el ID de tu empresa (CompanyId), 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 pertenece a la empresa del Webhook. |
403 🚫 | Webhook Bloqueado | El Webhook está inactivo o se ha auto-deshabilitado por seguridad (esto ocurre si alcanza 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 que se pueden hacer por segundo (Rate Limits). Para cumplir con esta regla y evitar bloqueos, Atom procesa estas peticiones en una fila de espera.
Por esta razón, cuando envías un Webhook desde HubSpot, siempre recibirás un código 202 (Aceptado).
Piénsalo como un restaurante: el código 202 es el mesero diciéndote "He tomado su pedido y lo envié a la cocina". Sin embargo, debes revisar la "nota" que te entrega el mesero (el cuerpo de la respuesta) para saber si hubo algún problema con los ingredientes una vez que llegó a la cocina.
¿Cómo leer la respuesta de Atom? (Ejemplo JSON)
Dentro de la respuesta 202, verás un bloque de datos. Aquí te explicamos qué significa cada campo clave:
{
"message": "...",
"hasErrors": true,
"outputFields": {
"success": false,
"httpStatus": 404,
"errorCode": "GEN_REQ_WEBHOOK_ERROR_002",
"errorMessage": "..."
}
}
hasErrors: Si es true, hubo un problema.
success: Si es false, el mensaje no se pudo procesar.
httpStatus: Es el código de error real (ej. 404 para "no encontrado").
errorCode: Es el código único del error. Úsalo para buscar la solución en las tablas de abajo.
Diccionario Completo de Errores (HubSpot)
📱 Contacto y Teléfono
Código de Error | ¿Qué significa? |
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 | ¿Qué significa? |
GEN_REQ_WEBHOOK_ERROR_002 | Webhook no encontrado (revisa la URL). |
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 el request. |
GEN_REQ_COMPANY_009 | Falta el 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 | ¿Qué significa? |
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 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 | ¿Qué significa? |
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 | ¿Qué significa? |
GEN_REQ_TOO_MANY_ERRORS_001 | Bloqueo Automático. Exceso de errores previos (umbral alcanzado). |
GEN_REQ_WEBHOOK_ERROR_008 | Falló la creación de la tarea en la fila de espera. |
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 plantilla desde el Workflow de HubSpot. |
GEN_REQ_WEBHOOK_ERROR_001 | Error inesperado (Fallback). |
Recepción de Eventos (POST /hubspot/webhook)
Código HTTP | ¿Qué significa? |
200 ✅ | Eventos procesados correctamente. |
400 ⚠️ | El formato enviado no es una lista de eventos válida. |
💡 Consejos para el Éxito
El Teléfono es la Llave: Incluye siempre la clave de país (ej. 521...).
Estado "Publicado": Los Webhooks solo funcionan si el flujo está publicado. Los borradores se ignoran.
Conversaciones con Agentes: Si tienes activada la "exclusión por agente", el mensaje automático no se enviará si el cliente ya está hablando con un humano.
Mapeo de Variables: Revisa que los nombres de los campos en tu sistema coincidan exactamente con las variables en Atom.
¿Necesitas ayuda técnica? Comparte siempre el errorCode con el equipo de soporte para una solución más rápida.