Ir al contenido
Documentation

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.

MétodoRutaObjetivo
GET/v1/webhooks/eventsEnumere los tipos de eventos compatibles actualmente.
GET/v1/webhooksEnumere los puntos finales de webhooks configurados.
POST/v1/webhooksRegistre 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-secretRote 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.

Ventana de terminal
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.

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:

EncabezadoObjetivo
X-CHAMPREP-SignatureFirma HMAC SHA-256 en sha256=<hex> formulario.
X-CHAMPREP-TimestampSe utiliza una marca de tiempo Unix en el contenido firmado.
X-CHAMPREP-Delivery-IdIdentificador único para la deduplicación.
X-CHAMPREP-EventTipo de evento para el enrutamiento.

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.

  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.

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.