Webhooks

Alem de consultar dados via REST, voce pode configurar webhooks para receber eventos em tempo real — sem polling, sem desperdicio de requisicoes.

Configuracao

Em Configuracoes > Desenvolvedores > Webhooks:

1. Informe a URL HTTPS do seu endpoint
2. Selecione os eventos que quer receber
3. Salve e copie o Signing Secret — use pra validar que o payload veio da Hunter

Eventos disponiveis

Contatos

• contact.created
• contact.updated
• contact.deleted

Empresas

• company.created
• company.updated
• company.deleted

Negocios

• deal.created
• deal.updated
• deal.stage_changed
• deal.won
• deal.lost

Conversas

• message.received
• message.sent

Planos de conta

• account_plan.approved
• account_plan.completed

Formato do payload

{
  "event": "deal.stage_changed",
  "workspaceId": "wks_abc123",
  "occurredAt": "2026-04-18T14:23:00.000Z",
  "data": {
    "id": "deal_xyz789",
    "title": "Proposta Acme Corp",
    "previousStage": "qualificacao",
    "newStage": "proposta",
    "...": "..."
  }
}

Assinatura e validacao

Cada entrega inclui o header X-Hunter-Signature contendo um HMAC-SHA256 do body bruto usando seu signing secret:

X-Hunter-Signature: sha256=abc123...

Valide antes de processar. Exemplo em Node.js:

import crypto from 'crypto'

function verify(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Retentativas

Entregas com falha (qualquer resposta non-2xx ou timeout de 10s) sao reenviadas com backoff exponencial:

• 1a retry: 30s depois
• 2a retry: 2min depois
• 3a retry: 10min depois
• 4a retry: 1h depois
• 5a retry: 6h depois

Depois da 5a, aparecem como falhas na pagina de Webhooks pra voce reprocessar manualmente.

Boas praticas

• Responda rapido — processe o payload em background, retornando 200 OK em <3 segundos
• Seja idempotente — eventos podem ser entregues mais de uma vez. Use occurredAt + data.id como chave de deduplicacao
• Ignore eventos desconhecidos — vamos adicionar novos tipos com o tempo; faca seu handler ignorar event que nao reconhece em vez de quebrar