Überblick
Passinstance bietet eine Dual-Mode-Webhook-Architektur, verwaltet über /api/v1/webhooks/subscriptions (bzw. unter Arbeitsbereich-Einstellungen -> Entwickler -> Webhooks unter /settings/workspace/developer/webhooks), damit Sie Wallet-Lebenszyklusereignisse mit jeder Infrastruktur synchronisieren können:
-
1
Push-Webhooks (
Push Webhook Dispatcher): Ausgehende HTTPS-POST-Callbacks in Echtzeit, signiert mit abonnementbezogenen HMAC-SHA256-Geheimnissen (X-Webhook-Signature), abgesichert durch SSRF-Zielvalidierung, automatische Wiederholungen mit exponentiellem Backoff und Jitter (DEFAULT_MAX_RETRIES = 5) sowie einen Endpunkt-spezifischen Circuit Breaker (CIRCUIT_BREAKER_THRESHOLD = 10aufeinanderfolgende Fehler,30Minuten Abkühlphase). -
2
Pull-Webhooks (
Webhook Pull API): Eine präfixfreie API zum Abfragen von Warteschlangen-Events (GET /webhook-payload/GET /api/v3/webhook-payloadundPOST /webhook-payload/acknowledge/POST /api/v3/webhook-payload/acknowledge) speziell für abgeschottete, On-Premise- oder lokale ERP-Server ohne öffentlich erreichbare HTTPS-Eingangsports.
Wichtig: Verifizieren Sie den Header
X-Webhook-Signaturestets anhand der rohen, ungeparsten HTTP-Request-Body-Bytes mitcrypto.timingSafeEqual, bevor Sie JSON parsen oder Geschäftslogik ausführen. Das erneute Serialisieren eines bereits geparsten JSON-Objekts verändert Leerzeichen oder Schlüsselreihenfolgen und macht die HMAC-Prüfsumme ungültig.
Dual-Mode-Webhook-Architektur
Endpunkte zur Abonnement-Verwaltung (Webhooks API)
| Methode | Endpunkt | Zweck |
|---|---|---|
| GET | /api/v1/webhooks | Ruft die Webhook-Übersicht und Zustellstatistiken des Arbeitsbereichs ab. |
GET / POST | /api/v1/webhooks/subscriptions | Listet ausgehende Webhook-Abonnements auf oder erstellt neue (events, HTTPS-url, optionale Filter). |
| PATCH | /api/v1/webhooks/subscriptions/:id | Aktualisiert abonnierte Events, Aktiv-Status oder Ziel-Endpunkt-URL. |
| DELETE | /api/v1/webhooks/subscriptions/:id | Löscht ein Webhook-Abonnement. |
| POST | /api/v1/webhooks/subscriptions/:id/regenerate-secret | Rotiert das HMAC-SHA256-Signaturgeheimnis für ein Abonnement. |
| POST | /api/v1/webhooks/subscriptions/:id/test | Sendet eine Diagnose-Testzustellung und setzt den Circuit-Breaker-Status zurück. |
| GET | /api/v1/webhooks/events | Liefert kanonische WebhookEventType-Metadaten und Beispiel-Payloads zurück. |
| GET | /api/v1/webhooks/history | Prüft historische Zustellungen und Zustellversuchs-Logs (/api/v1/webhooks/history/:eventHistoryId/attempts). |
1. Kanonische Event-Typen & Passinstance database-webhook event-Mapping
WebhookEventRegistry normalisiert 31 interne Passinstance database-webhook event-Domänenwerte in 11 kanonische WebhookEventType-Strings, die an Webhook-Empfänger ausgespielt werden (ältere Punkt-Notations-Aliase wie pass.created werden bei der Abonnement-Erstellung ebenfalls sauber zugeordnet):
Kanonischer WebhookEventType | Zugeordnete webhook event-Werte | Primärer Anwendungsfall |
|---|---|---|
pass_created | PASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASED | passId, externalId und Smart-Link in den CRM-Kontaktdatensatz zurückschreiben. |
pass_updated | PASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOG | Aktualisierte Treuestufe, externalId oder Prepaid-Guthaben im externen ERP spiegeln. |
pass_voided | PASS_VOIDED, PASS_REVOKED, PASS_DELETED | Gutscheincode in der E-Commerce-Checkout-Datenbank als verbraucht oder widerrufen markieren. |
first_pushnotification_registered | PUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOAD | Willkommensbonus-Workflow auslösen, wenn der Pass zum ersten Mal installiert wird. |
pushnotification_registered | PUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADED | Multi-Device-Nutzung erfassen (z. B. iPhone + gekoppelte Apple Watch). |
pushnotification_unregistered | PUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVED | Deinstallations-/Opt-out-Status im CRM aktualisieren oder Rückgewinnungssequenz starten. |
pass_template_created | TEMPLATE_CREATED | Entsprechende Kampagnen-Metadaten in externen Systemen bereitstellen. |
pass_template_updated | TEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATED | Zwischengespeicherte Vorlagen-Feldzuordnungen oder bundleId-Einstellungen aktualisieren. |
app_scan_created | APP_SCAN_CREATED, LOCATION_ENTERED | Filialbesuch, Treuegutschrift, Geofence-Eintritt oder Ticket-Check-in im BI erfassen. |
message_sent | MESSAGE_SENT, NOTIFICATION_SENT | Sperrbildschirm-Push oder Kampagnen-Zustellkontakt in der Kundenhistorie protokollieren. |
message_failed | MESSAGE_FAILED | Betriebsteam benachrichtigen oder Fallback-Kanal per SMS/E-Mail anstoßen. |
Ausgehende Push-HTTP-Header
Jeder ausgehende POST-Request von Push Webhook Dispatcher enthält:
POST /webhooks/passinstance HTTP/1.1
Host: api.yourcompany.com
Content-Type: application/json
User-Agent: Passinstance-Webhook/2.0
X-Webhook-Event: first_pushnotification_registered
X-Webhook-Id: evt_01hxyz9012ab44c8
X-Webhook-Timestamp: 2026-11-16T10:15:30.000Z
X-Webhook-Signature: sha256=4f8b92c1e0a73d6512f98e4b1c30a9d8721e4f60c3b8a192d4e7f012a3b4c5d6
HMAC-SHA256-Signaturprüfung (Node.js / TypeScript)
import * as crypto from 'crypto';
export function verifyPassinstanceWebhook(
rawBody: Buffer,
signatureHeader: string | undefined,
webhookSecret: string,
): boolean {
if (!signatureHeader || !signatureHeader.startsWith('sha256=')) {
return false;
}
const expectedSignature =
'sha256=' +
crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const actualBuffer = Buffer.from(signatureHeader, 'utf8');
const expectedBuffer = Buffer.from(expectedSignature, 'utf8');
if (actualBuffer.length !== expectedBuffer.length) {
return false;
}
return crypto.timingSafeEqual(actualBuffer, expectedBuffer);
}
SSRF-Schutz, Wiederholungen & Circuit Breaker
-
SSRF-Zielvalidierung (
Webhook URL Validator): Lehnt Registrierungen und Zustellungen an Loopback-Adressen (127.0.0.0/8,::1), private RFC-1918-Netze (10.0.0.0/8,172.16.0.0/12,192.168.0.0/16), Link-Local- und Cloud-Metadaten-IPs (169.254.169.254) ab. -
Exponentielles Backoff: Nicht-
2xx-Antworten oder Timeouts nach10s(DEFAULT_TIMEOUT_MS) werden bis zu 5-mal (DEFAULT_MAX_RETRIES) mit exponentiellem Backoff und Jitter wiederholt. -
Circuit Breaker: Nach 10 aufeinanderfolgenden Zustellfehlern (
CIRCUIT_BREAKER_THRESHOLD) öffnetcircuitOpenedAtden Circuit Breaker für eine 30-minütige Abkühlphase (CIRCUIT_BREAKER_COOLDOWN_MS), bevor erneut getestet wird.
2. Pull-Webhooks (Webhook Pull API)
Läuft Ihr Server hinter einer Unternehmens-Firewall oder NAT ohne öffentlichen eingehenden HTTPS-Zugriff, konfigurieren Sie einen Pull-Webhook und fragen eingereihte Events über ausgehendes HTTPS mittels GET /webhook-payload (oder Alias GET /api/v3/webhook-payload) ab:
Eingereihte Payloads abrufen (GET /webhook-payload)
GET /webhook-payload?webhookId=whk_01hxyz5512&limit=100&since=2026-11-16T08:00:00.000Z Header: x-api-key: pi_live_... (Standard-limit 100, max. 500)
{
"success": true,
"data": {
"items": [
{
"id": "wpl_01hxyz8801",
"event": "app_scan_created",
"createdAt": "2026-11-16T10:18:04.000Z",
"payload": {
"scanId": "scan_01hxyz7712ab",
"passId": "pass_loy_449102",
"externalId": "crm_cust_44910",
"decision": "SUCCESS"
}
}
],
"nextCursor": "wpl_01hxyz8801"
},
"description": "Webhook payloads retrieved successfully",
"errors": [],
"statusCode": 200
}
Verarbeitete Events bestätigen (POST /webhook-payload/acknowledge)
Sobald Ihr Worker den Stapel dauerhaft gespeichert hat, bestätigen Sie bis zur zuletzt verarbeiteten Payload-ID (POST /webhook-payload/acknowledge oder POST /api/v3/webhook-payload/acknowledge), sodass diese Events aus der Warteschlange entfernt werden:
{
"webhookId": "whk_01hxyz5512",
"upTo": "wpl_01hxyz8801"
}
Siehe auch Testen & Debugging sowie die Webhooks-API-Referenz für vollständige Payload-Schemas.
