Webhooks
Bereiten Sie Ihr Produkt auf Webhook-Ereignisse vor.
Erstellen und verwalten Sie Kunden-Webhook-Endpunkte für Nutzung, Abrechnung und API wichtige Lebenszyklusereignisse und bereiten Sie dann Empfänger auf signierte Zustellung, Wiederholungsversuche und redigierte Beobachtbarkeit vor.
Zuletzt aktualisiert: July 12, 2026. Examples Nutzung safe placeholders und tun nicht enthalten real Geheimnisse, API-Schluessels, oder customer Nutzdaten.
Empfängerregel
Bereiten Sie die Empfänger darauf vor, zunächst die Signatur der Rohnutzlast zu überprüfen, jede Ereignis-ID einmal aufzuzeichnen und 2xx erst dann zurückzugeben, wenn Ihre App das Ereignis sicher verarbeiten oder ignorieren kann.
Einrichtung-Pfad
Fünf Schritte vom Endpunkt URL bis zur Lieferbereitschaft.
Step 1
Erstellen Sie einen Empfängerendpunkt
Stellen Sie einen HTTPS URL bereit, der POST-Anfragen akzeptiert und den rohen Anfragetext vor dem Parsen von JSON lesen kann.
Step 2
Wählen Sie Ereignisse aus
Wählen Sie die Nutzungs-, Abonnement-, Rechnungs- oder API Schlüssellebenszyklus-Ereignistypen aus, für die Ihr Receiver bereit sein soll.
Step 3
Bewahren Sie das Signaturgeheimnis auf
Kopieren Sie das Endpunkt-Geheimnis einmal und speichern Sie es in einem Geheimnis-Manager, damit Empfänger für die signierte Webhook-Zustellung bereit sind.
Step 4
Planen Sie die Wiederholungsbehandlung
Entwerfen Sie idempotente Empfänger, sodass wiederholte Zustellungsversuche sicher sind, wenn das Senden von Webhooks aktiviert ist.
Step 5
Beobachtbarkeit planen
Verfolgen Sie jetzt den Endpunktstatus und definieren Sie die Zustellungsdatensätze, die Ihr Team für zukünftige Webhook-Versendungen benötigt.
Endpunkt URL
Registrieren Sie einen Endpunkt pro Umgebung.
Verwenden Sie separate URLs für Entwicklung, Staging und Produktion, damit zukünftige Testlieferungen keine Nebenwirkungen auf die Produktion auslösen.
{
"name": "Production usage events",
"url": "https://example.com/api/unlimitedcodex/webhook",
"events": [
"usage.threshold_reached",
"subscription.updated",
"invoice.payment_failed"
]
}Veranstaltungsauswahl
Wählen Sie Ereignistypen aus, für die Ihr Receiver bereit sein soll.
Halten Sie jeden Empfänger schmal, während die Lieferung vorbereitet wird. Ein Abrechnungsdienst benötigt möglicherweise nur Rechnungsereignisse, während eine Nutzungsleitlinie möglicherweise nur Schwellenwertereignisvorrichtungen benötigt.
| Veranstaltung | Triggerkontext | Anwendungsfall des Empfängers |
|---|---|---|
| use.threshold_reached | Ein Arbeitsbereich überschreitet einen konfigurierten Nutzungsschwellenwert. | Bereiten Sie Nachrichten an den Kontoinhaber vor, pausieren Sie teure Aufträge oder bitten Sie die Rechnungsinhaber, die Eignung des Pakets zu überprüfen. |
| Abonnement.aktualisiert | Der Abonnementstatus, das Paket oder der Abrechnungszeitraum ändern sich. | Aktualisieren Sie lokale Berechtigungen und Zugriffsdetails. |
| api_key.revoked | Ein API-Schlüssel wird widerrufen. | Machen Sie zwischengespeicherte Anmeldeinformationen ungültig und bereiten Sie eine Benachrichtigung für das Eigentümerteam vor. |
| Rechnung.bezahlt | Eine Rechnung wird als bezahlt markiert. | Entsperren Sie den kostenpflichtigen Zugriff, gleichen Sie den Abrechnungsstatus ab oder aktualisieren Sie Kontodatensätze. |
| Rechnung.Zahlung_fehlgeschlagen | Eine Rechnungszahlung schlägt fehl. | Bereiten Sie einen Mahnablauf, Nachrichten an Kontoinhaber oder Grenzwerte für riskante Hintergrundnutzung vor. |
Unterzeichnungsgeheimnis
Überprüfen Sie den Rohkörper vor der Verarbeitung.
Webhook-Signaturgeheimnisse werden einmal angezeigt. Speichern Sie das Geheimnis in einer Umgebungsvariablen oder einem Geheimnis-Manager und verwenden Sie es dann, um zeitgestempelte HMAC SHA-256-Signaturen zu validieren, wenn das Senden von Webhooks aktiviert ist.
signature value nutzt t=timestamp,v1=signature. Dies example names header x-ucx-signature; Nutzung signature header shown für Ihr Bereitstellung.
import { createHmac, timingSafeEqual } from "crypto";
function verifySignature(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(
signatureHeader.split(",").map((part) => part.split("="))
);
const timestamp = Number(parts.t);
const signature = parts.v1;
if (!Number.isInteger(timestamp) || !signature) {
return false;
}
const signedPayload = `${timestamp}.${rawBody}`;
const expected = createHmac("sha256", secret)
.update(signedPayload)
.digest("hex");
const left = Buffer.from(expected, "hex");
const right = Buffer.from(signature, "hex");
return left.length === right.length && timingSafeEqual(left, right);
}Beispiel eines Empfängers
Halten Sie die Handler klein und idempotent.
Verwenden Sie dieses Empfängermuster, sobald die ausgehende Zustellung aktiviert ist: Analysieren Sie das Ereignis nach der Signaturüberprüfung, zeichnen Sie die Ereignis-ID auf und übergeben Sie langsame Arbeit an Ihre eigene Warteschlange.
export async function POST(request) {
const rawBody = await request.text();
const signature = request.headers.get("x-ucx-signature") ?? "";
const secret = process.env.UCX_WEBHOOK_SECRET;
if (!secret || !verifySignature(rawBody, signature, secret)) {
return new Response("Invalid signature", { status: 400 });
}
const event = JSON.parse(rawBody);
// Store event.id before doing side effects so retries stay idempotent.
await recordWebhookEvent(event.id, event.type);
return Response.json({ received: true });
}Sichere Nutzlastform
Ereignisnutzlasten sollten als betriebliche Metadaten behandelt werden. Fügen Sie keine Eingabeaufforderungen, rohen API-Schlüssel, Zahlungskartendaten oder Kundengeheimnisse in Webhook-Einrichtungen oder Protokolle ein.
{
"id": "evt_example_123",
"type": "usage.threshold_reached",
"created": "2026-07-06T12:00:00.000Z",
"data": {
"workspaceId": "workspace_example",
"metric": "requests",
"thresholdPercent": 80
}
}Wiederholungen
Design für wiederholte Zustellversuche.
Wenn das Senden von Webhooks aktiviert ist, können Netzwerkfehler, Zeitüberschreitungen und Nicht-2xx-Antworten zu Wiederholungsversuchen führen. Erstellen Sie Handler, die dasselbe Ereignis mehr als einmal empfangen können, ohne dass es zu doppelten Nebenwirkungen kommt.
Rückkehr 2xx nach harter Arbeit
Schreiben Sie die Ereignis-ID oder stellen Sie die Arbeit in die Warteschlange, bevor Sie den Erfolg zurückgeben.
Verwenden Sie Ereignis-IDs für Idempotenz
Ignorieren Sie Duplikate, die bereits erfasst oder verarbeitet wurden.
Halten Sie die Mitarbeiter schnell
Verschieben Sie E-Mails, Rechnungssynchronisierung und lange Aufträge in eine interne Warteschlange.
Verlassen Sie sich nicht auf eine genaue Bestellung
Verwenden Sie nach Möglichkeit den aktuellen Ressourcenstatus, anstatt davon auszugehen, dass Ereignisse nacheinander eintreffen.
Beobachtbarkeit
Planen Sie den redigierten Endpunktkontext.
Planen Sie Zustellungsdatensätze anhand des geschwärzten Betriebskontexts wie Ereignistyp, Endpunkt, Status, Anzahl der Versuche, Antwortstatus, Antworttext, Zeitpunkt des nächsten Wiederholungsversuchs und Zustellzeit.
Erfordern HTTPS für Produktionsendpunkt-URLs.
Überprüfen Sie die zeitgestempelte Signatur HMAC, bevor Sie der Nutzlast vertrauen.
Speichern Sie Signaturgeheimnisse in einem Geheimmanager, nicht im Quellcode.
Behandeln Sie Ereignishandler als idempotent, da Zustellungsversuche wiederholt werden können.
Geben Sie 2xx erst zurück, nachdem das Ereignis sicher aufgezeichnet oder absichtlich ignoriert wurde.
Protokollieren Sie keine rohen Signaturgeheimnisse, API-Schlüssel, Zahlungsdetails, Eingabeaufforderungen oder Kundennutzdaten.
Lokale Tests
Vor der Produktion mit einem Tunnel testen.
Richten Sie einen Entwicklungs-Webhook-Endpunkt auf einen temporären Tunnel, bereiten Sie einen sicheren Ereigniseinbau vor, überprüfen Sie den Signaturhelfer und bestätigen Sie, dass Ihr Handler einen einzelnen Ereignisdatensatz speichert.
# Use a local tunnel URL as the endpoint while testing. https://your-tunnel.example/api/unlimitedcodex/webhook # Keep the signing secret out of source code. UCX_WEBHOOK_SECRET=whsec_ucx_placeholder_value
FAQ
Fragen zur Webhook-Einrichtung.
Welche Veranstaltungen kann ich abonnieren?
Die Webhook-Endpunktverwaltung des Kunden unterstützt die Auswahl von „Nutzung.threshold_reached“, „subscription.updated“, „api_key.revoked“, „voice.bezahlt“ und „voice.paid_failed“, sodass Empfänger konfiguriert werden können, bevor das Senden von Webhooks aktiviert wird.
Wie werden Webhook-Lieferungen signiert?
Bereiten Sie Empfänger auf eine zeitgestempelte HMAC SHA-256-Signatur vor. Der Signaturwert folgt dem Format „t=timestamp,v1=signature“ und Empfänger sollten ihn anhand des rohen Anforderungstexts und des Signaturgeheimnisses überprüfen.
Welche Lieferannahmen sollte mein Dienstleister treffen?
Wenn das Webhook-Versenden aktiviert ist, gehen Sie nicht von einer einzelnen Zustellung, einer strikten Reihenfolge oder einem erfolgreichen letzten Versuch aus. Erstellen Sie idempotente Handler und zeichnen Sie Ereignis-IDs auf, bevor Nebenwirkungen auftreten.
Kann ich ein Webhook-Signaturgeheimnis rotieren?
Ja. Durch Drehen eines Endpunkts wird ein neues Signaturgeheimnis erstellt, das einmal angezeigt wird. Speichern Sie den neuen Wert sicher und aktualisieren Sie den Empfänger, bevor Sie ihn in der Produktion verwenden.
Kostenlose Tools
Generieren Sie Webhook-Receiver-Starter
Gerüsthandler, Umgebungsdateien, bereichsbezogene Schlüssel und wiederversuchssichere Muster vor der Aktivierung von Abrechnungs- oder Nutzungsereignissen.
Webhook-Generator
Generieren Sie Node- oder Python-Webhook-Handler mit Signaturüberprüfung für unlimitedcodex-Ereignisse.
Env-Einrichtung
Generieren Sie.env.example-Blöcke aus ausgewählten Endpunkten, Umgebungen und Webhook-Anforderungen.
Scope-Konfigurator
Wählen Sie Workloads und Ausgabebereiche mit den geringsten Rechten,.env.example und eine Rotationscheckliste aus.
Simulator erneut versuchen
Optimieren Sie die Backoff- und Wiederholungseinstellungen, um simulierte Ergebnisse anzuzeigen und einen Wiederholungshandler-Snippet zu kopieren.
Sind Sie bereit, Eventempfänger vorzubereiten?
Koppeln Sie Webhooks mit Nutzungs- und Abrechnungskontrollen.
Überprüfen Sie die Paketanpassung, das Ratenbegrenzungsverhalten und die Fehlerbehandlung, bevor sich Kundenereignis-Arbeitsabläufe auf kundenorientierte Systeme auswirken.