Webhooks und SDKs
Webhooks Benachrichtigen Sie Ihr Backend über Geschäftsereignisse. Verwenden Sie sie zusammen mit API-Abfragen, damit eine verspätete oder ausbleibende Zustellung nicht dazu führt, dass Ihre Unterlagen ungelöst bleiben.
Vor der Verarbeitung prüfen
Die aktuelle Lieferung umfasst X-Webhook-Signature und X-Webhook-Timestamp. Die Signatur verwendet HMAC-SHA256 über dem Zeitstempel-Headertext, einen Punkt und den genauen rohen Anforderungstext. Sein Header-Wert hat die Form sha256=<HEX_SIGNATURE>.
- Behalten Sie den Rohkörper vor dem Parsen von JSON.
- Validieren Sie den Zeitstempel anhand der vereinbarten Uhrtoleranz.
- Überprüfen Sie die Signatur mit dem webhook-Geheimnis mithilfe eines Zeitkonstantenvergleichs.
- Interpretieren Sie erst dann die Nutzlast und aktualisieren Sie die Geschäftsunterlagen.
Durch die Neuformatierung des geparsten JSON vor der Überprüfung werden die signierten Bytes geändert. Die Webhook-Verifizierung verwendet das webhook-Geheimnis, nicht das API-Anfragegeheimnis oder den Kundenautorisierungsschlüssel.
Speichern und deduplizieren
Der Umschlag enthält event_id, event_type, created_at, tenant_id und data. Verwenden Sie für normale Ereigniszustellungen die verifizierte Ereignisidentität mit Ihrem Endpunkt- oder Arbeitsbereichskontext, um eine wiederholte Anwendung zu verhindern. Behalten Sie diese Entscheidung atomar mit der resultierenden Geschäftsaktualisierung bei oder stellen Sie das verifizierte Ereignis dauerhaft in die Warteschlange, bevor Sie es bestätigen.
X-Webhook-Idempotency-Key wird auch für normale Postausgangslieferungen bereitgestellt. Es handelt sich um Liefermetadaten, nicht um ein unabhängig signiertes Nutzlastfeld. Lassen Sie nicht zu, dass ein geänderter Header dazu führt, dass dasselbe verifizierte Ereignis zweimal Geld bewegt. Testlieferungen und manuelle Vorgänge können unterschiedliche Kennungen haben oder diesen Header weglassen.
Geben Sie eine erfolgreiche Antwort zurück, nachdem Sie das Ereignis dauerhaft angenommen haben. Entwerfen Sie für Duplikate und verzögerte oder nicht in der Reihenfolge liegende Ereignisse. Der Zeitstempel der Lieferung ist kein garantierter Zeitpunkt des Geschäftseintritts. Fragen Sie die zugrunde liegende Ressource ab, wenn ein Ereignis mit einem später bekannten Ergebnis in Konflikt steht.
Wählen Sie das Integrationspaket
Hierbei handelt es sich um Quellimplementierungsbereiche, nicht um eine Bestätigung der Verfügbarkeit der Paketregistrierung oder einer allgemeinen Veröffentlichung. Besorgen Sie sich beim Onboarding ein auf die Version abgestimmtes Paket und die zugehörigen Installationsanweisungen. Für andere Ressourcen sind möglicherweise direkte API-Anrufe erforderlich. Schließen Sie nicht auf einen vollständigen API-Client aus der Anwesenheit eines webhook-Pakets.
Testen Sie den Empfangspfad
Testen Sie eine gültige Zustellung, einen geänderten Text, eine ungültige Signatur, einen veralteten Zeitstempel, ein doppeltes Ereignis und einen Neustart des Empfängers. Bestätigen Sie die Wiederholungs- und Wiederholungsvereinbarungen mit der Integrationsumgebung. Fehlende Rückrufe sollten eine Versöhnung auslösen, nicht eine zweite Auszahlungsanfrage.