Zum Inhalt springen
Documentation

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.

MethodePfadZweck
GET/v1/webhooks/eventsListen Sie die derzeit unterstützten Ereignistypen auf.
GET/v1/webhooksListen Sie die konfigurierten Webhook-Endpunkte auf.
POST/v1/webhooksRegistrieren 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-secretWechseln 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.

Terminal-Fenster
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.

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:

HeaderZweck
X-CHAMPREP-SignatureHMAC-SHA-256-Signatur in sha256=<hex> Formular.
X-CHAMPREP-TimestampIm signierten Inhalt wird ein Unix-Zeitstempel verwendet.
X-CHAMPREP-Delivery-IdEindeutige Kennung zur Duplikatsbereinigung.
X-CHAMPREP-EventEreignistyp für das Routing.

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.

  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.

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.