#Como criar oportunidades a partir de um sistema externo (webhook)?

Configure uma Entrada externa com o gatilho Webhook recebido: a etapa ganha uma URL única e passa a criar uma oportunidade sempre que qualquer sistema — um formulário próprio, um ERP, um Zapier/Make, um script — enviar um POST com JSON para essa URL. Serve para quando não existe integração pronta com a plataforma de origem.

Não confunda com o Webhook de saída: aquele envia os dados da oportunidade para fora (veja como configurar). Este aqui recebe e cria o card.

Antes de começar

• Papel do workspace: proprietário, administrador ou editor. Quem não tem esse papel não consegue criar nem editar automações da etapa. Veja o alcance de cada papel na tabela de permissões.
• Você precisa de um pipeline com pelo menos uma etapa. Se ainda não tem, comece por Monte seu primeiro pipeline.
• Quem chama precisa conseguir enviar um POST com JSON — qualquer ferramenta que faça requisição HTTP serve.

#Passos

1. Abra o pipeline e, na etapa que vai receber as oportunidades, clique em Criar automação.
2. No passo Tipo, escolha Entrada externa e clique em Continuar.
3. Na categoria Webhooks, escolha Webhook recebido.
4. Clique em Adicionar entrada. A URL é gerada nesse momento.
5. Em Nesta etapa, ao lado, a nova entrada aparece com a URL. Clique nela para copiar e cole no seu sistema.

A URL não muda quando você salva a automação de novo — pode publicá-la no seu sistema sem medo de perder a integração.

#O que enviar no corpo do POST

O corpo precisa ser um objeto JSON e identificar o contato de pelo menos uma destas formas:

• email e/ou telephone — a plataforma procura um contato existente (deduplicação por e-mail e telefone). Se não encontrar, cria o contato.
• leadId — usa exatamente esse contato, sem criar nada.

Além da identificação, o corpo aceita campos do contato (name, document, instagram, birthday no formato AAAA-MM-DD, profession, city, state, address), customFields (campos customizados por nome) e tags (até 20 nomes). Os detalhes de cada campo, os limites e o que acontece com chaves extras estão em Como iniciar uma automação a partir de um sistema externo (webhook) — o corpo é exatamente o mesmo.

Exemplo:

{
  "email": "[email protected]",
  "name": "Maria Souza",
  "telephone": "5511999998888",
  "tags": ["webhook"]
}

A oportunidade é criada nesta etapa e vinculada ao contato identificado. As demais automações da etapa — atribuição, ação & delay — rodam normalmente sobre o card recém-criado.

#Respostas

#Chamadas repetidas e limites

• Repetição: envie o cabeçalho X-Idempotency-Key (ou o campo idempotencyKey no corpo) com um identificador seu. Reenvios com a mesma chave dentro de 24 horas contam como uma chamada só — não nascem duas oportunidades. Se a chamada falhar, a chave é liberada.
• Tamanho e ritmo: o corpo aceita até 32 KB, e cada origem pode enviar até 300 chamadas por minuto.

#Proteja a URL

A URL é o segredo — quem tiver o endereço consegue criar oportunidades no seu pipeline. Trate-a como uma senha e não a publique. Se desconfiar que ela vazou, exclua a entrada e crie outra: a URL antiga passa a responder erro na hora.

#Relacionados

• Avise outro sistema quando a oportunidade entrar numa etapa
• Como iniciar uma automação a partir de um sistema externo (webhook)
• Monte seu primeiro pipeline

#Se não funcionou

• Criar automação não aparece na etapa → seu papel não permite configurar o pipeline. Confira em Sem permissão e na tabela de permissões.
• Não achou Webhook recebido na lista → ele fica na categoria Webhooks, e só aparece em Entrada externa. Em Gatilho de passagem ele não existe: o webhook cria a oportunidade, não move uma já existente.
• A chamada respondeu 202 mas o card não apareceu → confira se a automação está ativa na etapa. Automação pausada registra a chamada e cria o contato, mas não cria a oportunidade.
• Nasceram dois cards para o mesmo pedido → seu sistema enviou duas chamadas sem chave de idempotência. Passe o X-Idempotency-Key com um identificador do pedido.
• Para ver as chamadas que chegaram, clique no card da automação na etapa: a automação abre e o gatilho mostra as últimas chamadas recebidas, com o corpo enviado e o resultado.