Skip to content
Hilfecenter-Anleitung · Entwickler-API
4 Min. LesezeitGeprüft 2026-11-16

Webhooks & Ereignisse

Abonnieren Sie Lebenszyklus-Callbacks (Hinzugefügt, Entfernt, Gescannt, Aktualisiert) und prüfen Sie HMAC-SHA256-Signaturen.

In dieser Anleitung

Ü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. 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 = 10 aufeinanderfolgende Fehler, 30 Minuten Abkühlphase).
  2. 2
    Pull-Webhooks (Webhook Pull API): Eine präfixfreie API zum Abfragen von Warteschlangen-Events (GET /webhook-payload / GET /api/v3/webhook-payload und POST /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-Signature stets anhand der rohen, ungeparsten HTTP-Request-Body-Bytes mit crypto.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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
DUAL-MODE-PUSH- & -PULL-WEBHOOK-ZUSTELLUNG
STUFE 01 Passinstance Event Bus
STUFE 02 Modus 1: Push-Webhook-Zustellung (Push Webhook Dispatcher)
1
Ziel-URL prüfen (Webhook URL Validator: private/SSRF-IPs blockieren)
2
Payload signieren (Webhook Signing EngineX-Webhook-Signature: sha256=<hmac>)
3
POST an Kunden-HTTPS-Endpunkt (User-Agent: Passinstance-Webhook/2.0)
4
Bei 5xx / Timeout (10s Standard): Bis zu 5x mit Jitter-Exponential-Backoff wiederholen +-- 5. Nach 10 Fehlern in Folge: Circuit Breaker auslösen (30 Min. Pause)
STUFE 03 Modus 2: Pull-Webhook-Warteschlange (Webhook Pull API)
-- 1. Event-Payload in Mandanten-Pull-Puffer einreihen -- 2. Firewall-geschützter Client fragt ab: GET/webhook-payload?webhookId=...&limit=100&since=... +-- 3. Client bestätigt verarbeiteten Cursor: POST/webhook-payload/acknowledge { upTo: "wpl_01hxyz...", webhookId }

Endpunkte zur Abonnement-Verwaltung (Webhooks API)

MethodeEndpunktZweck
GET/api/v1/webhooksRuft die Webhook-Übersicht und Zustellstatistiken des Arbeitsbereichs ab.
GET / POST/api/v1/webhooks/subscriptionsListet ausgehende Webhook-Abonnements auf oder erstellt neue (events, HTTPS-url, optionale Filter).
PATCH/api/v1/webhooks/subscriptions/:idAktualisiert abonnierte Events, Aktiv-Status oder Ziel-Endpunkt-URL.
DELETE/api/v1/webhooks/subscriptions/:idLöscht ein Webhook-Abonnement.
POST/api/v1/webhooks/subscriptions/:id/regenerate-secretRotiert das HMAC-SHA256-Signaturgeheimnis für ein Abonnement.
POST/api/v1/webhooks/subscriptions/:id/testSendet eine Diagnose-Testzustellung und setzt den Circuit-Breaker-Status zurück.
GET/api/v1/webhooks/eventsLiefert kanonische WebhookEventType-Metadaten und Beispiel-Payloads zurück.
GET/api/v1/webhooks/historyPrü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 WebhookEventTypeZugeordnete webhook event-WertePrimärer Anwendungsfall
pass_createdPASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASEDpassId, externalId und Smart-Link in den CRM-Kontaktdatensatz zurückschreiben.
pass_updatedPASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOGAktualisierte Treuestufe, externalId oder Prepaid-Guthaben im externen ERP spiegeln.
pass_voidedPASS_VOIDED, PASS_REVOKED, PASS_DELETEDGutscheincode in der E-Commerce-Checkout-Datenbank als verbraucht oder widerrufen markieren.
first_pushnotification_registeredPUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOADWillkommensbonus-Workflow auslösen, wenn der Pass zum ersten Mal installiert wird.
pushnotification_registeredPUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADEDMulti-Device-Nutzung erfassen (z. B. iPhone + gekoppelte Apple Watch).
pushnotification_unregisteredPUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVEDDeinstallations-/Opt-out-Status im CRM aktualisieren oder Rückgewinnungssequenz starten.
pass_template_createdTEMPLATE_CREATEDEntsprechende Kampagnen-Metadaten in externen Systemen bereitstellen.
pass_template_updatedTEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATEDZwischengespeicherte Vorlagen-Feldzuordnungen oder bundleId-Einstellungen aktualisieren.
app_scan_createdAPP_SCAN_CREATED, LOCATION_ENTEREDFilialbesuch, Treuegutschrift, Geofence-Eintritt oder Ticket-Check-in im BI erfassen.
message_sentMESSAGE_SENT, NOTIFICATION_SENTSperrbildschirm-Push oder Kampagnen-Zustellkontakt in der Kundenhistorie protokollieren.
message_failedMESSAGE_FAILEDBetriebsteam benachrichtigen oder Fallback-Kanal per SMS/E-Mail anstoßen.

Ausgehende Push-HTTP-Header

Jeder ausgehende POST-Request von Push Webhook Dispatcher enthält:

HTTP
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)

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 nach 10s (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) öffnet circuitOpenedAt den 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)

JSON
{
  "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:

JSON
{
  "webhookId": "whk_01hxyz5512",
  "upTo": "wpl_01hxyz8801"
}

Siehe auch Testen & Debugging sowie die Webhooks-API-Referenz für vollständige Payload-Schemas.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.