Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks permitem que a Vendaze notifique seu aplicativo quando eventos ocorrem no workspace. Em vez de fazer polling continuamente, seu servidor recebe uma notificação HTTP assim que algo muda.
Webhooks são configurados pelo cliente da Vendaze no painel da plataforma, não via API pública. Este guia explica como receber e validar as notificações.

Como funciona

  1. O cliente da Vendaze configura um webhook no painel: define a URL de destino e os eventos desejados
  2. O Vendaze gera um webhook_secret único para aquele endpoint
  3. Quando um evento ocorre, a Vendaze faz um POST para a URL configurada com o payload assinado
  4. Seu servidor valida a assinatura e processa o evento

Eventos disponíveis

EventoQuando ocorre
person.createdUma nova pessoa é criada
person.updatedUma pessoa é atualizada
company.createdUma nova empresa é criada
company.updatedUma empresa é atualizada
deal.createdUm novo negócio é criado
deal.updatedUm negócio é atualizado
activity.createdUma nova atividade é registrada
activity.updatedUma atividade é atualizada
task.createdUma nova tarefa é criada
task.updatedUma tarefa é atualizada
product.createdUm novo produto é criado
product.updatedUm produto é atualizado

Formato do payload

{
  "event": "person.created",
  "workspace_slug": "workspace-do-cliente",
  "timestamp": "2026-05-26T14:00:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "Ana Costa",
    "emails": [{ "email": "ana@empresa.com", "reminder": "work" }],
    "created_at": "2026-05-26T14:00:00Z"
  }
}

Validar a assinatura

Cada entrega é assinada com HMAC-SHA256 usando o webhook_secret. Valide antes de processar. Headers enviados pelo Vendaze:
X-Vendaze-Signature: sha256=abc123...
X-Vendaze-Timestamp: 1748000000
Validação em Node.js:
const crypto = require('crypto');

function isValidSignature(body, timestamp, receivedSignature, secret) {
  // Rejeitar payloads com mais de 5 minutos
  const now = Math.floor(Date.now() / 1000);
  if (now - parseInt(timestamp) > 300) return false;

  const message = `${timestamp}.${JSON.stringify(body)}`;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(message).digest('hex');

  return crypto.timingSafeEqual(Buffer.from(receivedSignature), Buffer.from(expected));
}
Rejeite payloads com timestamp superior a 5 minutos. Isso protege contra ataques de replay.

Política de reenvio

Se seu servidor não retornar status 2xx em 10 segundos, a Vendaze tenta novamente:
TentativaEspera
21 minuto
35 minutos
430 minutos
52 horas
Após 5 falhas consecutivas, o endpoint é marcado como suspended. O cliente reativa no painel.

Boas práticas

  • Responda rapidamente: retorne 200 imediatamente e processe em background.
  • Seja idempotente: o mesmo evento pode chegar mais de uma vez. Use o id do payload para deduplicar.
  • Guarde os logs: armazene os payloads recebidos para facilitar debug e auditoria.