Webhooks

Los webhooks envían los eventosCHAMPREP compatibles a su punto final HTTPS. Reducen las consultas periódicas y permiten que las integraciones respondan a los cambios a medida que se producen.

La gestión de webhooks requiere el webhooks:manage Ámbito de aplicación.

Puntos finales de gestión

Método	Ruta	Objetivo
GET	/v1/webhooks/events	Enumere los tipos de eventos compatibles actualmente.
GET	/v1/webhooks	Enumere los puntos finales de webhooks configurados.
POST	/v1/webhooks	Registre un punto final HTTPS y una lista de eventos.
PATCH	/v1/webhooks/{webhookId}	Actualice la URL, los eventos, la descripción o el estado activo.
DELETE	/v1/webhooks/{webhookId}	Elimine un punto final.
POST	/v1/webhooks/{webhookId}/rotate-secret	Rote su clave de firma.

Consulta /v1/webhooks/events en lugar de codificar de forma fija un catálogo de eventos. Los tipos de eventos admitidos pueden ampliarse a medida que los servicios añaden eventos públicos.

Registre un punto final

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

El secreto de firma se devuelve cuando se crea el punto final o cuando se renueva su secreto. Almacénelo inmediatamente en un gestor de secretos; no se trata de una claveAPI de portador y debe ser exclusivo del punto final del webhook.

Formato de entrega

Cada entrega se realiza mediante HTTPS POST con un cuerpo JSON:

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

Los encabezados de entrega incluyen:

Encabezado	Objetivo
X-CHAMPREP-Signature	Firma HMAC SHA-256 en sha256=<hex> formulario.
X-CHAMPREP-Timestamp	Se utiliza una marca de tiempo Unix en el contenido firmado.
X-CHAMPREP-Delivery-Id	Identificador único para la deduplicación.
X-CHAMPREP-Event	Tipo de evento para el enrutamiento.

Verifique la firma

Calcule el HMAC SHA-256 sobre los bytes exactos en UTF-8 de <timestamp>.<raw-request-body> utilizando el secreto de firma del punto final. Compare las firmas esperadas y las recibidas mediante una comparación en tiempo 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 el cuerpo sin procesar antes de que un marco de trabajo lo analice y lo vuelva a serializar. Un objeto reserializado puede generar bytes diferentes y no superar la verificación.

Evite la repetición y el trabajo duplicado

1. Rechace cualquier marca de tiempo que se encuentre fuera de la ventana de tolerancia corta que haya elegido.
2. Almacene los identificadores de entrega procesados al menos durante el tiempo que dure su ventana de reintentos.
3. Considere un ID de entrega repetido como ya procesado y devuelva una respuesta de éxito.
4. Realice las tareas de negocio de forma idempotente siempre que sea posible.

Comportamiento de entrega

Devuelva una respuesta de éxito 2xx Responda sin demora y traslade las tareas que consumen muchos recursos a una cola. Los tiempos de espera, los fallos de red, 429; los errores del servidor pueden reintentarse. Los fallos persistentes pueden provocar que se desactive un punto final, por lo que debe supervisar el estado de entrega y corregir sin demora las URL que fallen.

No registre secretos de firma ni cargas útiles completas confidenciales. Rote el secreto si puede haber quedado expuesto y, a continuación, actualice el receptor antes de aceptar nuevas entregas.