Webhooks

Les webhooks transmettent les événementsCHAMPREP pris en charge à votre point de terminaison HTTPS. Ils réduisent les interrogations régulières et permettent aux intégrations de réagir aux changements dès qu’ils se produisent.

La gestion des webhooks nécessite la webhooks:manage portée.

Points de terminaison de gestion

Méthode	Parcours	Objectif
GET	/v1/webhooks/events	Veuillez énumérer les types d’événements actuellement pris en charge.
GET	/v1/webhooks	Répertoriez les points de terminaison de webhooks configurés.
POST	/v1/webhooks	Enregistrez un point de terminaison HTTPS et une liste d’événements.
PATCH	/v1/webhooks/{webhookId}	Mettez à jour l’URL, les événements, la description ou l’état d’activité.
DELETE	/v1/webhooks/{webhookId}	Supprimez un point de terminaison.
POST	/v1/webhooks/{webhookId}/rotate-secret	Effectuez une rotation de sa clé de signature.

Requête /v1/webhooks/events plutôt que de coder en dur un catalogue d’événements. Les types d’événements pris en charge peuvent s’étendre à mesure que les services ajoutent des événements publics.

Enregistrer un point de terminaison

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

La clé de signature est renvoyée lors de la création du point de terminaison ou lors de la rotation de sa clé. Enregistrez-la immédiatement dans un gestionnaire de secrets ; il ne s’agit pas d’une cléAPI « bearer » et elle doit être unique au point de terminaison du webhook.

Format de transmission

Chaque transmission s’effectue via HTTPS POST avec un corps JSON :

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

Les en-têtes de transmission comprennent :

En-tête	Objectif
X-CHAMPREP-Signature	Signature HMAC SHA-256 dans sha256=<hex> formulaire.
X-CHAMPREP-Timestamp	Horodatage Unix utilisé dans le contenu signé.
X-CHAMPREP-Delivery-Id	Identifiant unique pour la déduplication.
X-CHAMPREP-Event	Type d’événement pour le routage.

Vérifiez la signature

Calculez un HMAC SHA-256 sur les octets UTF-8 exacts de <timestamp>.<raw-request-body> en utilisant la clé de signature du point de terminaison. Comparez les signatures attendues et reçues à l’aide d’une comparaison en temps constant.

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);
}

Vérifiez le corps brut avant qu’un framework ne l’analyse et ne le resérialise. Un objet resérialisé peut produire des octets différents et échouer à la vérification.

Prévenir la relecture et le double travail

1. Rejetez tout horodatage se situant en dehors de la courte fenêtre de tolérance que vous avez choisie.
2. Conservez les identifiants de transmission traités au moins pendant la durée de votre fenêtre de réessai.
3. Considérez un identifiant de transmission répété comme déjà traité et renvoyez une réponse de réussite.
4. Effectuez les tâches métier de manière idempotente dans la mesure du possible.

Comportement de livraison

Renvoyez une réponse indiquant que l’opération a réussi 2xx Répondez rapidement et transférez les tâches coûteuses vers une file d’attente. Les délais d’expiration, les pannes réseau, 429; les erreurs de serveur peuvent faire l’objet d’une nouvelle tentative. Les échecs persistants peuvent entraîner la désactivation d’un point de terminaison ; veillez donc à surveiller l’état de livraison et à corriger rapidement les URL défaillantes.

Ne consignez pas les secrets de signature ni les charges utiles sensibles complètes. Effectuez la rotation du secret s’il a pu être compromis, puis mettez à jour le destinataire avant d’accepter de nouvelles livraisons.