Webhooks

Webhooks übermitteln unterstützte EreignisseCHAMPREP an Ihren HTTPS-Endpunkt. Sie reduzieren das Polling und ermöglichen es Integrationen, auf Änderungen zu reagieren, sobald diese eintreten.

Die Webhook-Verwaltung erfordert die webhooks:manage Geltungsbereich.

Verwaltungs-Endpunkte

Methode	Pfad	Zweck
GET	/v1/webhooks/events	Listen Sie die derzeit unterstützten Ereignistypen auf.
GET	/v1/webhooks	Listen Sie die konfigurierten Webhook-Endpunkte auf.
POST	/v1/webhooks	Registrieren Sie einen HTTPS-Endpunkt und eine Ereignisliste.
PATCH	/v1/webhooks/{webhookId}	Aktualisieren Sie die URL, die Ereignisse, die Beschreibung oder den Aktivitätsstatus.
DELETE	/v1/webhooks/{webhookId}	Löschen Sie einen Endpunkt.
POST	/v1/webhooks/{webhookId}/rotate-secret	Wechseln Sie dessen Signaturschlüssel regelmäßig.

Abfrage /v1/webhooks/events anstatt einen Ereigniskatalog fest zu programmieren. Die unterstützten Ereignistypen können erweitert werden, sobald Dienste öffentliche Ereignisse hinzufügen.

Registrieren Sie einen Endpunkt

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

Der Signaturschlüssel wird bei der Erstellung des Endpunkts oder bei der Rotation seines Schlüssels zurückgegeben. Speichern Sie ihn unverzüglich in einem Schlüsselmanager; es handelt sich nicht um einen Bearer-SchlüsselAPI und er sollte für den Webhook-Endpunkt eindeutig sein.

Übermittlungsformat

Jede Übermittlung erfolgt über HTTPS POST mit einem JSON-Body:

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

Zu den Übermittlungs-Headern gehören:

Header	Zweck
X-CHAMPREP-Signature	HMAC-SHA-256-Signatur in sha256=<hex> Formular.
X-CHAMPREP-Timestamp	Im signierten Inhalt wird ein Unix-Zeitstempel verwendet.
X-CHAMPREP-Delivery-Id	Eindeutige Kennung zur Duplikatsbereinigung.
X-CHAMPREP-Event	Ereignistyp für das Routing.

Überprüfen Sie die Signatur

Berechnen Sie HMAC-SHA-256 über die exakten UTF-8-Bytes von <timestamp>.<raw-request-body> unter Verwendung des Signaturschlüssels des Endpunkts. Vergleichen Sie die erwarteten und die empfangenen Signaturen mit einem Vergleich in konstanter Zeit.

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

Überprüfen Sie den Rohtext des Hauptteils, bevor ein Framework diesen analysiert und erneut serialisiert. Ein erneut serialisiertes Objekt kann zu unterschiedlichen Bytes führen und die Überprüfung nicht bestehen.

Verhindern Sie Wiederholungen und Doppelarbeit

1. Lehnen Sie einen Zeitstempel ab, der außerhalb des von Ihnen gewählten kurzen Toleranzfensters liegt.
2. Speichern Sie verarbeitete Zustell-IDs mindestens für die Dauer Ihres Wiederholungsfensters.
3. Behandeln Sie eine wiederholte Zustell-ID als bereits verarbeitet und geben Sie eine erfolgreiche Antwort zurück.
4. Führen Sie geschäftliche Vorgänge nach Möglichkeit idempotent aus.

Übermittlungsverhalten

Geben Sie eine erfolgreiche 2xx Reaktion umgehend und verlagern Sie rechenintensive Aufgaben in eine Warteschlange. Zeitüberschreitungen, Netzwerkausfälle, 429; Serverfehler können erneut versucht werden. Anhaltende Fehler können dazu führen, dass ein Endpunkt deaktiviert wird; überwachen Sie daher den Zustellstatus und korrigieren Sie fehlerhafte URLs umgehend.

Protokollieren Sie keine Signaturgeheimnisse oder vollständige sensible Nutzdaten. Wechseln Sie das Geheimnis, falls es offengelegt worden sein könnte, und aktualisieren Sie anschließend den Empfänger, bevor Sie neue Zustellungen annehmen.