Webhooks

Os webhooks entregam eventosCHAMPREP compatíveis ao seu endpoint HTTPS. Eles reduzem a necessidade de polling e permitem que as integrações respondam às alterações à medida que elas ocorrem.

O gerenciamento de webhooks requer o webhooks:manage escopo.

Endpoints de gerenciamento

Método	Caminho	Objetivo
GET	/v1/webhooks/events	Liste os tipos de eventos atualmente suportados.
GET	/v1/webhooks	Liste os endpoints de webhook configurados.
POST	/v1/webhooks	Registre um endpoint HTTPS e uma lista de eventos.
PATCH	/v1/webhooks/{webhookId}	Atualize a URL, os eventos, a descrição ou o estado ativo.
DELETE	/v1/webhooks/{webhookId}	Exclua um endpoint.
POST	/v1/webhooks/{webhookId}/rotate-secret	Faça a rotação de seu segredo de assinatura.

Consulta /v1/webhooks/events em vez de codificar um catálogo de eventos de forma rígida. Os tipos de eventos suportados podem ser ampliados à medida que os serviços adicionam eventos públicos.

Registre um endpoint

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $CHAMPREP_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/champrep",
    "events": ["contact.created"],
    "description": "Contact synchronization"
  }' \
  https://api.champrep.com/v1/webhooks

O segredo de assinatura é retornado quando o endpoint é criado ou quando seu segredo é rotacionado. Armazene-o imediatamente em um gerenciador de segredos; ele não é uma chaveAPI de portador e deve ser exclusivo para o endpoint do webhook.

Formato de entrega

Cada entrega é uma conexão HTTPS POST com um corpo JSON:

{
  "id": "delivery_identifier",
  "type": "contact.created",
  "timestamp": "2026-08-08T12:00:00Z",
  "data": {}
}

Os cabeçalhos de entrega incluem:

Cabeçalho	Objetivo
X-CHAMPREP-Signature	Assinatura HMAC SHA-256 em sha256=<hex> formulário.
X-CHAMPREP-Timestamp	Timestamp Unix utilizado no conteúdo assinado.
X-CHAMPREP-Delivery-Id	Identificador único para deduplicação.
X-CHAMPREP-Event	Tipo de evento para roteamento.

Verifique a assinatura

Calcule o HMAC SHA-256 sobre os bytes exatos em UTF-8 de <timestamp>.<raw-request-body> utilizando o segredo de assinatura do endpoint. Compare as assinaturas esperadas e recebidas por meio de uma comparação em tempo constante.

import crypto from 'node:crypto';

export function verifyChamprepWebhook(rawBody, headers, secret) {
  const timestamp = String(headers['x-champrep-timestamp'] || '');
  const received = String(headers['x-champrep-signature'] || '');
  const expected = `sha256=${crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')}`;

  const receivedBytes = Buffer.from(received);
  const expectedBytes = Buffer.from(expected);
  return receivedBytes.length === expectedBytes.length
    && crypto.timingSafeEqual(receivedBytes, expectedBytes);
}

Verifique o corpo bruto antes que uma estrutura o analise e o resseriialize. Um objeto resseriializado pode produzir bytes diferentes e falhar na verificação.

Evite repetição e trabalho duplicado

1. Rejeite um carimbo de data/hora fora da janela de tolerância curta escolhida.
2. Armazene os IDs de entrega processados pelo menos durante o período de sua janela de repetição de tentativas.
3. Trate um ID de entrega repetido como já processado e retorne uma resposta de sucesso .
4. Execute tarefas de negócios de forma idempotente sempre que possível.

Comportamento de entrega

Retorne uma resposta bem-sucedida 2xx resposta imediatamente e transfira tarefas onerosas para uma fila. Tempos limite, falhas de rede, 429; erros de servidor podem ser repetidos. Falhas persistentes podem levar à desativação de um endpoint; portanto, monitore o estado de entrega e corrija prontamente as URLs com falha.

Não registre segredos de assinatura nem cargas úteis sensíveis completas. Faça a rotação do segredo se ele tiver sido exposto e, em seguida, atualize o destinatário antes de aceitar novas entregas.