Bloco de Resposta de Webhook - Envie Respostas HTTP Personalizadas aos Chamadores

Visão Geral

O Bloco de Resposta de Webhook permite enviar uma resposta HTTP personalizada de volta ao sistema que chamou seu Bloco de Webhook. Sem este bloco, o ChatMaxima responde com um 200 OK genérico e um corpo de {"status":"success"}. Isso é suficiente para a maioria dos retornos de chamada, mas algumas integrações esperam um formato, código de status ou tipo de conteúdo específico antes de considerarem a entrega bem-sucedida.

Use o Bloco de Resposta de Webhook quando o chamador é rigoroso quanto à resposta: gateways de pagamento que tentam novamente a menos que vejam um campo JSON específico, sistemas SOAP legados que esperam XML, ferramentas de iPaaS que analisam a resposta em etapas subsequentes ou construtores de formulários que exibem a resposta ao usuário.

Bloco de Webhook vs. Bloco de Resposta de Webhook

Aspecto	Bloco de Webhook	Bloco de Resposta de Webhook
Direção	Recebe chamada HTTP de entrada	Envia a resposta HTTP de volta ao chamador
Posicionamento	Primeiro bloco ou no meio do fluxo	Em qualquer lugar após um Bloco de Webhook
Obrigatório	Sim (para aceitar chamadas externas)	Opcional (um 200 OK padrão é enviado se omitido)
Finalidade	Acionar ou retomar o fluxo	Moldar a resposta HTTP ao chamador

Onde Encontrá-lo

1. Abra seu chatbot no Studio
2. Arraste o bloco Resposta de Webhook da barra lateral esquerda para o canvas
3. Conecte-o após o bloco de Webhook que recebeu a requisição
4. Dê um clique duplo no bloco para configurá-lo

O bloco de Resposta de Webhook não precisa ser o bloco imediatamente seguinte. Você pode colocar blocos de Condição, API, Definir Variável e Mensagem entre o bloco de Webhook e o bloco de Resposta de Webhook. Quando o bloco de resposta é alcançado durante a execução do fluxo, sua configuração se torna a resposta HTTP ao chamador original.

Configuração

Etapa 1: Defina o Código de Status HTTP

Código de Status	Use Quando
200	Padrão. Indica sucesso para a maioria dos chamadores
201	Útil quando o webhook criou um recurso (ex.: uma nova conversa)
202	Aceito para processamento assíncrono (o bot agirá sobre ele depois)
400	Rejeitar cargas malformadas
401	Rejeitar chamadores não autorizados
500	Indicar uma falha do lado do bot para lógica de nova tentativa

Etapa 2: Defina o Content-Type

Content-Type	Use Quando
application/json	A maioria das integrações modernas (padrão)
application/xml	Chamadores legados no estilo SOAP
text/plain	Retornos de chamada no estilo de verificação de integridade
text/html	Confirmações de envio de formulário exibidas a um usuário

Etapa 3: Escreva o Corpo da Resposta

O corpo é um campo de texto livre. Escreva a carga exata que você quer retornar ao chamador. As variáveis capturadas anteriormente no fluxo podem ser inseridas com a sintaxe {variable_name} (chaves simples).

Para JSON:

{
  "received": true,
  "conversation_id": "{conversation_id}",
  "lead_id": "{reference_id}",
  "acknowledged_at": "{current_time}"
}

Para XML:

<response>
  <status>success</status>
  <conversation_id>{conversation_id}</conversation_id>
</response>

Para texto puro:

OK

Etapa 4: Envie e Salve

Clique em Enviar no modal do bloco, depois salve o fluxo usando Salvar Alterações na barra superior.

Como Funciona

External system POSTs to webhook URL
                 │
                 ▼
       Webhook Block fires
                 │
                 ▼
   (Optional) intermediate blocks:
   - Condition to validate payload
   - API Block to enrich data
   - Set Variable to compute fields
                 │
                 ▼
    Webhook Response Block reached
                 │
                 ▼
    Custom HTTP response returned
    to the original caller
                 │
                 ▼
    Flow continues to downstream blocks
    (messages, further logic, etc.)

A resposta HTTP é enviada de forma síncrona: o chamador externo permanece conectado até o bloco de resposta ser alcançado. Por isso, mantenha rápido o caminho entre o bloco de Webhook e o bloco de Resposta de Webhook. Evite chamadas de API de longa duração ou lógica demorada antes do bloco de resposta, caso contrário o chamador pode expirar.

Casos de Uso Comuns

Confirmar com o ID da Conversa

Uma ferramenta de iPaaS (n8n, Zapier, Make) quer registrar o ID da conversa no seu próprio sistema após acionar o webhook.

• Código de Status: 201
• Content-Type: application/json
• Corpo:

{
  "created": true,
  "conversation_id": "{conversation_id}",
  "reference_id": "{reference_id}"
}

Retornar o Resultado da Validação

Um construtor de formulários envia (POST) a entrada do usuário. O bot a valida e retorna um aprovado/reprovado para que o formulário possa exibir a mensagem certa.

• Código de Status: 200
• Content-Type: application/json
• Corpo:

{
  "valid": true,
  "message": "Your request has been received"
}

Rejeitar Cargas Inválidas

Combine um bloco de Condição (verificando campos obrigatórios) com um bloco de Resposta de Webhook na ramificação de falha que retorna 400.

• Código de Status: 400
• Content-Type: application/json
• Corpo:

{
  "error": "missing_required_field",
  "field": "{missing_field}"
}

Confirmação de Gateway de Pagamento

Um gateway de pagamento envia (POST) um webhook de settle. O bot precisa retornar um formato JSON específico ou o gateway continuará tentando novamente.

• Código de Status: 200
• Content-Type: application/json
• Corpo:

{
  "status": "acknowledged",
  "transaction_id": "{transaction_id}"
}

Recibo de Entrega de SMS

Um provedor de SMS legado espera uma resposta de texto puro OK.

• Código de Status: 200
• Content-Type: text/plain
• Corpo: OK

Boas Práticas

• Mantenha o caminho curto. Coloque blocos entre o Webhook e a Resposta de Webhook apenas se eles forem rápidos. Chamadas de API longas devem vir após o bloco de resposta para que o chamador não expire
• Sempre responda rapidamente para chamadores que tentam novamente. Gateways de pagamento e provedores de SMS costumam tentar novamente em segundos. Alcançar o bloco de resposta em um ou dois segundos evita notificações duplicadas
• Corresponda exatamente ao formato esperado pelo chamador. Chamadores rigorosos rejeitam respostas mesmo quando o código de status está correto. Leia a documentação da integração e teste com as requisições de exemplo dela
• Use blocos de Condição para ramificar a resposta. Tenha um bloco de Resposta de Webhook na ramificação de sucesso e outro diferente (com 400 ou 401) na ramificação de falha
• Inclua o ID da conversa ou de referência. Isso facilita correlacionar os logs do chamador com a conversa no ChatMaxima
• Não coloque dados sensíveis na resposta. A resposta fica visível ao chamador. Retorne apenas o que ele precisa para confirmar o recebimento

Solução de Problemas

O chamador recebe o 200 OK padrão em vez da minha resposta personalizada

1. Confirme que um bloco de Resposta de Webhook está presente e é alcançável a partir do bloco de Webhook
2. Verifique o grafo do fluxo: se uma Condição desvia do bloco de resposta, o padrão é usado
3. Certifique-se de que o bloco foi salvo. Clique em Enviar no modal, depois em Salvar Alterações na barra superior

O chamador tenta novamente repetidamente

1. Garanta que o código de status corresponde ao que o chamador considera sucesso. Alguns provedores aceitam apenas 200, não 201 ou 202
2. Verifique se o corpo da resposta corresponde ao formato esperado pelo chamador. Consulte a documentação ou os logs dele
3. Verifique se há blocos anteriores entre o Webhook e a Resposta de Webhook que sejam lentos. O chamador pode estar expirando antes de a resposta ser enviada

As variáveis aparecem como {variable_name} bruto no corpo da resposta

1. Confirme que a variável foi definida por um bloco anterior no mesmo fluxo
2. Os nomes das variáveis são sensíveis a maiúsculas. Verifique a grafia
3. Para campos aninhados, use a notação de ponto: {customer.email}, não {customer_email}
4. Se a variável vem da carga do webhook recebido, certifique-se de que a carga realmente continha o campo

JSON malformado é rejeitado por chamadores rigorosos

1. Valide o modelo do corpo como JSON antes de salvar. Uma variável sem aspas em um campo de string produzirá JSON inválido se o valor contiver aspas ou quebras de linha
2. Para campos numéricos como {amount}, não use aspas. Para campos de string, sempre use aspas: "name": "{name}"
3. Teste com uma chamada de exemplo (usando curl ou Postman) para ver os bytes reais retornados

Incompatibilidade de Content-Type

1. Alguns chamadores exigem application/json; charset=utf-8 explicitamente. O padrão envia application/json sem o charset
2. Clientes SOAP podem exigir text/xml em vez de application/xml. Consulte a documentação da integração

Próximas Etapas

• Bloco de Webhook - Receba chamadas HTTP de entrada para acionar ou retomar um fluxo
• Bloco de API - Chame APIs externas a partir do fluxo
• Visão Geral do Studio - Explore todos os tipos de bloco e os recursos do construtor de fluxos