Webhook

Este documento descreve o comportamento da rota de webhook, com foco em como o payload recebido é preservado, sanitizado e disponibilizado durante a execução do fluxo em variables.system.webhook.

Visão Geral

A rota aceita qualquer JSON válido enviado pelo integrador.

O payload é armazenado integralmente, com uma versão sanitizada para uso seguro nos fluxos.

Durante o processamento, o Runner expõe:

• O payload original (raw)

• O payload sanitizado (sem espaços ou caracteres inválidos em chaves)

• O mapa de transformação entre chaves originais e sanitizadas

---

Fluxo de Processamento

1. Recepção do Payload

• A API aceita qualquer JSON.

• Campos comuns (external_id, text, data, payload) são opcionais.

• Caso external_id não seja enviado:

  • Um UUID é gerado automaticamente

  • Retornado na resposta como external_session_id

---

2. Persistência dos Dados

Após o recebimento:

• O corpo original é armazenado como:

  • webhook.payload

Sanitização

• Espaços e caracteres inválidos em chaves são removidos.

• Exemplo:

  • "phone number" → "phonenumber" → webhook.payload.phonenumber

---

4. Resposta da API

• A rota responde com 202 Accepted

• Campos retornados:

  • external_session_id

⚠️ Nenhum outro campo do payload é modificado na resposta.

O integrador deve considerar o JSON enviado como fonte de verdade.

---

Boas Práticas

• Envie external_id sempre que possível para:

  • Facilitar rastreamento

  • Manter sessões longas ou multi-etapas

• Utilize sempre a versão sanitizada (payload) em:

  • Templates

  • Condições

  • Interpolação de texto

• Consulte sanitized_fields quando:

  • Usar chaves com espaços

  • Depurar integrações

• Use raw apenas quando precisar do JSON exatamente como recebido

---

Exemplo Prático

Payload Enviado

{
  "external_id": "cliente-42",
  "text": "confirmado",
  "data": {
        "CNPJ": "1231313131",
        "Name": "Thiago Thamiel",
        "business": null,
        "email": "[email protected]",
        "phone number": "11941489395"
    }
}

---

Acesso no Fluxo (Recomendado)

{{ variables.system.webhook.payload.data.CNPJ }}
{{ variables.system.webhook.payload.data.phonenumber }}

---

Considerações Finais

• Esse comportamento é exclusivo para:

  • provider_type = webhook

• Outros canais (WhatsApp, Telegram, etc.):

  • Mantêm a estrutura tradicional de metadata

  • Não aplicam sanitização automática de chaves

---