Webhooks

Os eventos

Evento	Quando
contact.created	Um contato foi criado
contact.updated	Um contato mudou
card.created	Uma ficha foi criada
card.updated	Uma ficha mudou
card.stage_changed	Uma ficha mudou de etapa

Avisam igual, venha a mudança de onde vier: o app, a API, um formulário, uma mensagem que chega ou um agente de IA.

Criar um webhook

Os donos e administradores os criam em Integrações › Para desenvolvedores › Webhooks: o endereço, os eventos e uma descrição. Ao criar, você recebe o segredo para verificar a assinatura, mostrado uma única vez. Também podem ser criados pela API, com POST /v1/webhooks: é o que o Zapier e o Make fazem.

O endereço precisa ser https:// em um domínio público (porta 443).

O que chega

Cada aviso traz o contato ou a ficha completos, como a API os devolve, e nos *.updated, qual campo mudou:

{
  "id": "6f0c2a1e-…",
  "type": "contact.updated",
  "timestamp": "2026-11-10T15:04:05.123Z",
  "data": { "id": "…", "name": "João Silva", "emails": [], "customFields": {} },
  "changedFields": ["name"]
}

A ordem não é garantida: use timestamp, que é a hora da mudança. Os avisos são assinados: veja como verificar a assinatura.

Novas tentativas

Conta como entregue um 2xx em até 10 segundos. Se o seu sistema não responde, tentamos de novo 8 vezes ao longo de umas 44 horas. Um 410 desliga o webhook; 3 dias seguidos falhando também, e avisamos você.

Em Webhooks você vê cada entrega com a resposta, e pode reenviá-la ou mandar uma de teste.