Skip to content
REST-API-Referenz & SDKs

Passinstance Entwickler-Dokumentation

Erstellen Sie hochvolumige Apple Wallet (.pkpass) und Google Wallet Integrationen. Ausstellen, aktualisieren, scannen und Echtzeit-Benachrichtigungen über produktive REST-APIs übertragen.

API-Schlüssel erhalten
Live-Docs-Workbench — Codebeispiele aktualisieren sich während der Eingabe

Übersicht & Endpunkte

4 Endpunkte
Webhooks

Webhooks-Übersicht & Signaturprüfung

Prüfen Sie X-Webhook-Signature als HMAC-SHA256 über den unveränderten Anfragebody mit Ihrem Abonnement-Secret. Vergleichen Sie in konstanter Zeit und verarbeiten Sie Ereignisse idempotent.

Signatur-Header
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Zeitstempel-Header
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Replay-Schutz

Gleichen Sie X-Webhook-Id mit der signierten eventId ab, deduplizieren Sie Ereignisse und prüfen Sie den signierten Zeitstempel gemäß Ihrer Replay-Richtlinie.

Unterstützte Ereignisse

PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED

Erwartete Antwort

Geben Sie innerhalb von 5.000 ms HTTP 200 OK zurück, um den Empfang zu bestätigen

Öffentlicher Signaturschlüssel

GET /api/v1/webhooks/public-key liefert den aktiven öffentlichen Schlüssel zur Signaturprüfung

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsAPI-Schlüssel
Übersicht & Endpunkte

Webhook-Abonnement erstellen

HTTPS-Endpunkt registrieren, um HMAC-signierte Echtzeit-Ereignisbenachrichtigungen für Pass-Ausgabe, Updates, Scans und Deinstallationen zu erhalten.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage mit Ziel-HTTPS-URL und Liste von Webhook-Ereignistypen-Elementen.

Anfrage-Body2 erforderlich • 5 fakultativ
urlstring (HTTPS URL)
Erforderlich

Ihre Server-Endpunkt-URL (muss mit https:// beginnen, max. 2048 Zeichen).

Beispiel: https://your-server.com/webhooks/passinstance
eventsstring[] (enum)
Erforderlich

Webhook-Ereignistypen-Werte: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

Beispiel: ["PASS_CREATED", "PASS_UPDATED", "APP_SCAN_CREATED"]

Antwort-Statuscodes

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}API-Schlüssel
Übersicht & Endpunkte

Webhook abbestellen

Ein aktives Webhook-Abonnement anhand seiner ID löschen und zukünftige Ereigniszustellungen an den Endpunkt beenden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des zu entfernenden Webhook-Abonnements.

Beispiel: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsAPI-Schlüssel
Übersicht & Endpunkte

Webhook-Abonnements auflisten

Alle aktiven Webhook-Abonnements abrufen, die für Ihren Kunden-Workspace registriert sind.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyÖffentlich
Übersicht & Endpunkte

Öffentlichen Webhook-Signaturschlüssel abrufen

Den aktiven öffentlichen PEM-Schlüssel von Passinstance abrufen, um asymmetrische Webhook-Signaturen kryptografisch zu prüfen.

Antwort-Statuscodes

Pull-basierte Webhooks

2 Endpunkte
Webhooks

Funktionsweise & Grenzen von Pull-Webhooks

Verarbeiten Sie Pass- und Scan-Ereignisse in Echtzeit über ausgehende HMAC-SHA256-Push-Webhooks (mit exponentiellem Backoff und Circuit-Breakern) oder eingehendes Pull-Webhook-Polling für Firewall-geschützte Umgebungen sowie No-Code-Workflows.

Push-Webhook-Ausfallsicherheit

5 Wiederholungen mit jittered exponentiellem Backoff; Circuit Breaker öffnet nach 10 aufeinanderfolgenden Fehlern

Pull-Webhook-Polling

GET /api/v1/webhook-payload & POST /api/v1/webhook-payload/acknowledge für private Netzwerke

Workflow-Trigger

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Workflow-Aktionen

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadAPI-Schlüssel
Pull-basierte Webhooks

Ausstehende Pull-Webhook-Ereignisse abfragen

Ausstehende Webhook-Ereignis-Payloads über ausgehendes HTTPS GET für Firewall-geschützte oder private Netzwerke ohne offene Eingangsports abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter3 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeAPI-Schlüssel
Pull-basierte Webhooks

Pull-Webhook-Ereignisse bestätigen

Verarbeitete Pull-Webhook-Payloads bis zu einer angegebenen Payload-ID bestätigen, sodass sie als zugestellt markiert und aus der Warteschlange entfernt werden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage mit Angabe der High-Water-Mark-Payload-ID (upTo).

Anfrage-Body1 erforderlich • 1 fakultativ
upTostring (UUID)
Erforderlich

Zuletzt verarbeitete Webhook-Payload-ID; alle Ereignisse bis einschließlich dieser ID werden bestätigt.

Beispiel: whp_55a4b3c2-1d0e-9f8a-7b6c-5d4e3f2a1b0c

Antwort-Statuscodes

Webhook-Ereignisse

4 Leitfäden
Webhook-EreignisseAusgehende HTTP-POST-Webhook-Benachrichtigung

Vorlagen-Ereignisse (Template Events)

Ausgehende HTTP-POST-Webhook-Benachrichtigungen, wenn eine Pass-Vorlage erstellt, aktualisiert, veröffentlicht oder gelöscht wird.

Vorlage erstellt
POST
TEMPLATE_CREATED

Wird ausgelöst, wenn eine neue Pass-Vorlage erstellt wird

Vorlage aktualisiert
POST
TEMPLATE_UPDATED

Wird ausgelöst, wenn Vorlagenfelder, Layout oder Mechaniken geändert werden

Vorlage veröffentlicht
POST
TEMPLATE_PUBLISHED

Wird ausgelöst, wenn ein Vorlagenentwurf für aktive Pässe veröffentlicht wird

Vorlage gelöscht
POST
TEMPLATE_DELETED

Wird ausgelöst, wenn die Vorlagenlöschung und der Wallet-Widerruf starten

Webhook-EreignisseAusgehende HTTP-POST-Webhook-Benachrichtigung

Pass-Ereignisse (Pass Events)

Ausgehende HTTP-POST-Webhook-Benachrichtigungen für jeden Lebenszyklusschritt eines Passes von der Erstellung bis zur Geräteentfernung.

Pass erstellt
POST
PASS_CREATED

Wird sofort ausgelöst, wenn ein neuer Pass über die REST-API oder PassFlow ausgestellt wird

Pass aktualisiert
POST
PASS_UPDATED

Wird ausgelöst, wenn Pass-Attribute, Treuepunkte, Stufe oder Guthaben geändert werden

Pass entwertet
POST
PASS_VOIDED

Wird ausgelöst, wenn ein Pass in Apple Wallet & Google Wallet entwertet oder deaktiviert wird

Erstmaliger Pass-Download
POST
PASS_FIRST_DOWNLOAD

Wird beim ersten Abruf oder Download des Passes durch den Kunden ausgelöst

Pass heruntergeladen
POST
PASS_DOWNLOADED

Wird bei jedem weiteren Download des Pass-Pakets oder Google-Wallet-Links ausgelöst

Pass vom Gerät entfernt
POST
PASS_REMOVED

Wird ausgelöst, wenn der Nutzer den Pass aus Apple Wallet oder Google Wallet löscht

Webhook-EreignisseAusgehende HTTP-POST-Webhook-Benachrichtigung

Scan-Ereignisse (Scan Events)

Ausgehende HTTP-POST-Webhook-Benachrichtigungen in Echtzeit, sobald ein Pass-Barcode oder NFC-Pass gescannt und validiert wird.

Pass-Scan erstellt
POST
APP_SCAN_CREATED

Wird ausgelöst, wenn POST /api/v1/scans oder ein Scanner einen Scan aufzeichnet

Scan-Metadaten

Enthält passId, serialNumber, templateId, configId, Scan-Entscheidung und Saldoänderung

Zustellgarantie

Mindestens einmalige HTTPS-POST-Zustellung mit X-Webhook-Id und X-Webhook-Signature

Pull-Queue-Kompatibilität

Auch über GET /api/v1/webhook-payload für geschützte Kassensysteme abrufbar

Webhook-EreignisseAusgehende HTTP-POST-Webhook-Benachrichtigung

Nachrichten-Ereignisse & Status-Referenz (Message Events)

Ausgehende HTTP-POST-Webhook-Benachrichtigungen und Zustellstatuscodes für Wallet-Push-Nachrichten, E-Mail-Kampagnen und SMS.

Nachricht gesendet
POST
MESSAGE_SENTNOTIFICATION_SENT

Wird ausgelöst, wenn eine Pass-Nachricht oder ein Push gesendet wird

Zustellung fehlgeschlagen
POST
MESSAGE_FAILED

Wird ausgelöst, wenn eine ausgehende E-Mail, SMS oder Push-Nachricht fehlschlägt

Nachrichten-Statusreferenz

QUEUED -> SENT -> DELIVERED (oder FAILED / BOUNCED mit Diagnosecode)

Idempotente Ereigniskorrelation

Abgleich von eventId und passId im Webhook-Consumer zur Deduplizierung von Wiederholungen