Configuracao de Webhooks

Webhooks permitem que sua aplicacao receba notificacoes em tempo real quando eventos ocorrem no Tesselys. Ao inves de fazer polling periodico, o Tesselys envia uma requisicao HTTP POST para a URL que voce configurar.

Criando uma Assinatura de Webhook

Via Painel Administrativo

1. Acesse Configuracoes → Integracoes → Webhooks
2. Clique em Nova assinatura
3. Preencha:
   • URL: endpoint HTTPS que recebera os eventos
   • Eventos: selecione os eventos desejados
   • Secret: sera gerado automaticamente (copie e armazene)
4. Clique em Salvar

Via API

curl -X POST "https://api.tesselys.com.br/external/v1/webhooks" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://sua-aplicacao.com.br/webhooks/tesselys",
    "events": ["person.created", "deal.created", "deal.updated", "financial.settled"],
    "description": "Integracao com sistema legado"
  }'

Resposta (201):

{
  "id": "clxwh001",
  "url": "https://sua-aplicacao.com.br/webhooks/tesselys",
  "events": ["person.created", "deal.created", "deal.updated", "financial.settled"],
  "description": "Integracao com sistema legado",
  "secret": "whsec_a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuVwXyZ",
  "isActive": true,
  "createdAt": "2026-03-25T10:00:00.000Z"
}

Importante

O campo secret e exibido apenas na criacao. Copie e armazene em local seguro. Ele sera necessario para validar a assinatura dos eventos recebidos.

Requisitos da URL de Webhook

Requisito	Descricao
Protocolo	Deve ser HTTPS (HTTP nao e aceito)
Certificado SSL	Valido e emitido por CA reconhecida (nao autoassinado)
Resposta	Deve retornar status 200 em ate 5 segundos
Disponibilidade	O endpoint deve estar acessivel publicamente

Politica de Retry

Se a URL nao responder com status 200 dentro de 5 segundos, o Tesselys retentar o envio:

Tentativa	Intervalo	Acumulado
1a	Imediato	0s
2a	30 segundos	30s
3a	2 minutos	2m 30s
4a	10 minutos	12m 30s
5a	1 hora	1h 12m 30s

Apos 5 tentativas sem sucesso, o evento e marcado como falho e a assinatura pode ser desativada automaticamente se acumular muitas falhas consecutivas.

Formato do Payload

Todos os webhooks sao enviados como POST com Content-Type: application/json:

POST https://sua-aplicacao.com.br/webhooks/tesselys
Content-Type: application/json
X-Webhook-Id: evt_clx123abc456
X-Webhook-Signature: sha256=a1b2c3d4e5f6...
X-Webhook-Timestamp: 1711324800

{
  "id": "evt_clx123abc456",
  "event": "person.created",
  "timestamp": "2026-03-25T10:30:00.000Z",
  "data": {
    "id": "clx2b3c4d5e6f7g8h9i0j1k2",
    "name": "Maria Oliveira",
    "personType": "INDIVIDUAL",
    "email": "maria@email.com"
  }
}

Gerenciando Assinaturas

Listar assinaturas

curl -X GET "https://api.tesselys.com.br/external/v1/webhooks" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}"

Atualizar assinatura

curl -X PUT "https://api.tesselys.com.br/external/v1/webhooks/clxwh001" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["person.created", "person.updated", "deal.created"],
    "url": "https://nova-url.com.br/webhooks/tesselys"
  }'

Desativar assinatura

curl -X DELETE "https://api.tesselys.com.br/external/v1/webhooks/clxwh001" \
  -H "Authorization: Bearer {accessToken}" \
  -H "x-company-token: {companyToken}"

Boas Praticas

• Responda rapido: processe o evento de forma assincrona (fila, worker) e retorne 200 imediatamente
• Idempotencia: use o campo id do evento para evitar processamento duplicado
• Valide a assinatura: sempre verifique o header X-Webhook-Signature (veja Validacao)
• Monitore falhas: configure alertas para quando webhooks falharem repetidamente
• Registre logs: armazene os payloads recebidos para auditoria e debug