🚀 Conceitos Básicos

Os Webhooks funcionam como "portas de entrada" que permitem a sistemas externos (como seu CRM ou seu site) indicar ao Atom que envie uma mensagem automática a um cliente.

Ao receber uma solicitação, Atom emite uma resposta imediata por meio de um código de status numérico. Que Atom receba a mensagem com sucesso significa que a ordem foi aceita pelo sistema; porém, a entrega final ao dispositivo do cliente dependerá de que os dados sejam válidos e das políticas vigentes do WhatsApp.

1. Webhooks Padrão (Integrações Próprias)

Se você utiliza um sistema próprio ou outro software direto, o Webhook é executado de forma imediata e o servidor devolverá os seguintes códigos HTTP:

Código HTTP	Significado	Detalhes e Solução
200 ✅	Executado com sucesso	Atom recebeu a informação e o fluxo foi executado corretamente.
400 ⚠️	Dados incorretos ou faltantes	Pode faltar o ID do Webhook, o ID da sua empresa (`CompanyId`), a informação do canal ou parâmetros obrigatórios requeridos pelo seu fluxo.
401 🔐	Erro de segurança (Token)	Falta o token de autorização, o formato não é válido (deve ser tipo Bearer) ou o token não corresponde à empresa do Webhook.
403 🚫	Webhook bloqueado	O Webhook está inativo ou foi desabilitado por segurança após alcançar um limite crítico de 1.000 erros consecutivos.
404 🔍	Não encontrado	O Webhook, o canal ou a empresa a qual você está tentando chamar não existe no sistema ou foi eliminada.
500 🛠️	Erro interno	Ocorreu uma falha inesperada nos servidores da Atom. Tente novamente mais tarde.

2. Webhooks com HubSpot (Processamento Assíncrono)

A Regra do Código 202

HubSpot impõe limites estritos na quantidade de solicitações permitidas por segundo (Rate Limits). Para cumprir com essa regra e evitar bloqueios, Atom processa essas solicitações em uma fila de espera assíncrona.

Por isso, quando você envia um Webhook do HubSpot, Atom sempre devolverá de entrada um código 202 (Aceito).

💡 Dica: O código 202 funciona como a confirmação de recebimento do pedido. Para conhecer o resultado real do processamento, você deve inspecionar a resposta JSON devolvida dentro do objeto de saída.

Leitura da Resposta JSON

Dentro do corpo da resposta com código 202, você visualizará a seguinte estrutura de dados:

JSON

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

hasErrors: Se for true, indica que ocorreu um problema durante o processo.
success: Se for false, a solicitação não pôde ser processada com sucesso.
httpStatus: Mostra o código de erro HTTP real (por exemplo, 404 para "não encontrado").
errorCode: Código único do erro utilizado para identificar a causa específica nas tabelas de referência.

🔍 Dicionário Completo de Erros (HubSpot)

📱 Contato e Telefone

Código de Erro	Significado
`GEN_REQ_PHONE_001`	Falta o telefone. Não foi enviado um número de contato.
`GEN_REQ_PHONE_002`	Telefone inválido. O número não tem o formato correto para WhatsApp.
`GEN_REQ_WEBHOOK_ERROR_006`	Falta o identificador do webhook ou o número de telefone na solicitação.

⚙️ Configuração do Fluxo e Canal

Código de Erro	Significado
`GEN_REQ_WEBHOOK_ERROR_002`	Webhook não encontrado (revise a URL enviada).
`GEN_REQ_WEBHOOK_ERROR_003`	Webhook não registrado no sistema.
`GEN_REQ_WEBHOOK_ERROR_004`	Webhook inativo ou desabilitado.
`GEN_REQ_WEBHOOK_ERROR_005`	ID do Webhook inválido.
`GEN_REQ_WEBHOOK_ERROR_007`	Faltam parâmetros obrigatórios na solicitação.
`GEN_REQ_COMPANY_009`	Falta o ID da empresa (`Company ID`).
`GEN_REQ_CHANNEL_003`	Canal não encontrado. A linha do WhatsApp não existe ou está desconectada.
`GEN_REQ_CHANNEL_004`	O canal não tem um `App ID` associado.
`GEN_REQ_TEMPLATE_005`	Modelo não encontrado. O modelo não existe mais.
`GEN_REQ_TEMPLATE_006`	Dados do modelo inválidos. Variáveis mal mapeadas.
`GEN_REQ_ACTION_001`	Ação de início do fluxo não encontrada.

🔐 Segurança e Credenciais

Código de Erro	Significado
`GEN_REQ_AUTHORIZATION_TOKEN_001`	Falta o token de autorização.
`GEN_REQ_AUTHORIZATION_TOKEN_002`	Formato de token inválido.
`GEN_REQ_AUTHORIZATION_TOKEN_003`	O token enviado não corresponde à sua conta.
`GEN_REQ_CRED_007`	Credenciais não encontradas.
`GEN_REQ_INT_008`	Integração não encontrada.

👨‍💻 Agentes e Atribuições

Código de Erro	Significado
`GEN_REQ_AGENT_001`	Agente do fluxo não encontrado.
`GEN_REQ_AGENT_002`	Agente do fluxo inativo.
`GEN_REQ_APPID_001`	`App ID` do agente não encontrado.

⚠️ Sistema e Erros Críticos

Código de Erro	Significado
`GEN_REQ_TOO_MANY_ERRORS_001`	Bloqueio Automático. Excesso de erros anteriores acumulados (limite alcançado).
`GEN_REQ_WEBHOOK_ERROR_008`	Falha na criação da tarefa na fila de espera assíncrona.
`GEN_NOT_FOUND_010`	Recurso de suporte ou entidade não suportada.
`GEN_NOT_FOUND_011`	Entidade não encontrada.
`INT_HS_WORKFLOW_002`	Erro ao enviar o modelo do Workflow do HubSpot.
`GEN_REQ_WEBHOOK_ERROR_001`	Erro inesperado do sistema (Fallback).

📩 Recebimento de Eventos (POST /hubspot/webhook)

Código HTTP	Significado
200 ✅	Eventos processados corretamente.
400 ⚠️	O formato enviado não é uma lista de eventos válida.

💡 Dicas para o Sucesso

Siga essas recomendações técnicas para garantir o envio correto de suas comunicações:

O telefone é a chave: Sempre inclua o código do país (exemplo: 521...) de acordo com o formato requerido pelo WhatsApp.
Status "Publicado": Os Webhooks funcionam apenas se o fluxo conversacional estiver no status Publicado. Os fluxos em rascunho são ignorados.
Conversas com Agentes: Se você mantiver ativa a "exclusão por agente", a mensagem automática não será enviada se o cliente estiver conversando com um assessor humano.
Mapeamento de Variáveis: Revise que os nomes dos campos enviados pelo seu sistema correspondam exatamente aos nomes das variáveis configuradas no Atom.

⚠️ Importante: Se você precisar de assistência técnica com nossa equipe de suporte, sempre compartilhe o valor de errorCode para acelerar o tempo de resposta e diagnóstico.

Dominar os códigos de resposta e o dicionário de erros permite que você diagnostique integrações em tempo recorde e mantenha suas automações operando sem interrupções. Tome o controle de seus Webhooks e escale seus fluxos com total confiança! ✅

📘 Guia de Respostas e Erros de Webhooks em Atom