# Webhook: cadastre contatos e dispare fluxos de fora da plataforma

E se o seu site, CRM ou sistema interno pudesse **cadastrar um contato e disparar uma jornada completa no WhatsApp com uma única chamada**? É exatamente isso que o gatilho **Webhook** faz — a integração mais poderosa dos fluxos.

## O que acontece em uma chamada

Quando o seu sistema envia um POST para a URL do fluxo, a plataforma:
1. **Busca o contato** pelo telefone ou e-mail — e **cadastra automaticamente** se não existir
2. **Abre a conversa** no canal configurado (ou reutiliza a que já estiver aberta)
3. **Dispara o fluxo** na hora — template, mensagens, consultas, tudo
4. Deixa **todos os campos do payload disponíveis como variáveis** (`{{variables.campo}}`)

## Configurando o gatilho

Crie (ou duplique) um fluxo e, no nó de **Gatilho**, escolha **Webhook (HTTP POST)**:

![Gatilho Webhook](https://chat.simplesdesk.com.br/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMlltQmc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--8c511cb5a8c25506ba9d634874ee737761cf2d76/tutorial-webhook-01-gatilho-webhook.jpg)

- **URL do Webhook** — o endereço que o sistema externo vai chamar. Salve o fluxo para gerar a URL definitiva. 🔐 **Trate como senha**: quem tem a URL dispara o fluxo. Vazou? Use **Regenerar token**.
- **Canal** — onde a conversa será criada. **Selecione sempre** que o fluxo enviar mensagens.

## O payload

```
POST https://chat.simplesdesk.com.br/webhooks/flows/SEU_TOKEN
Content-Type: application/json

{
  "phone_number": "+5511999998888",
  "name": "Maria da Silva",
  "email": "maria@exemplo.com",
  "pedido_id": "123"
}
```

Regras de ouro:
- `phone_number` **sempre no formato internacional** `+55` + DDD + número — formato diferente duplica contato
- Envie `phone_number` **ou** `email` (é assim que o contato é localizado/criado)
- **Qualquer campo extra vira variável**: `pedido_id` acima fica disponível como `{{variables.pedido_id}}` em todas as mensagens e nós do fluxo — sem configurar nada

A resposta da chamada confirma o resultado: `{"received": true, "contact_id": …, "conversation_id": …}`.

## Capturar exemplo: mapeie campos com cliques

Clique em **Capturar exemplo** e peça um POST de teste ao sistema externo — o payload real aparece na tela e os campos são sugeridos para mapeamento:

![Capturar exemplo aguardando](https://chat.simplesdesk.com.br/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMmdtQmc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--7fd717a3f013725fdd1a90c07459b0bb63a4a131/tutorial-webhook-03-capturar-exemplo.jpg)

## Mapeamento e política de conversa

![Mapeamento e política](https://chat.simplesdesk.com.br/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMmNtQmc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--e6914186ce497657dba61be3bf8ca689c5630157/tutorial-webhook-02-mapeamento-politica.jpg)

- **Mapeamento de campos do payload** — grava campos do payload direto **na ficha do contato** (campos padrão ou atributos personalizados). Sem mapeamento, o dado continua disponível como variável — só não persiste no cadastro.
- **Se já houver conversa aberta/pendente** — escolha entre *Reutilizar e executar o fluxo* (padrão), *Reutilizar sem executar* ou seguir pela saída especial **"Conversa existente"** do gatilho, que permite tratar esse caso num caminho próprio.
- **Requisições recentes** — o log de todas as chamadas recebidas (sucesso e erro, com o payload): o primeiro lugar para investigar quando "não chegou".

## Casos de uso

- **Formulário do site** → cadastro + primeira mensagem em segundos
- **CRM/ERP** → evento no sistema (proposta enviada, boleto vencendo) dispara a régua no WhatsApp
- **Vários números**: crie um fluxo por canal (cada um com a sua URL) e distribua os cadastros entre as URLs no seu sistema — protege os números e organiza a operação

> 💡 Dica: enviando os dados que o fluxo usaria para perguntar (ex.: CPF), dá para **pular etapas de coleta** com uma Condição Avançada no início: variável presente → segue direto; ausente → pergunta normalmente.