Skip to content
REST API-referentie & SDK's

Passinstance Documentatie voor Ontwikkelaars

Bouw grootschalige Apple Wallet (.pkpass) en Google Wallet integraties. Uitgeven, bijwerken, scannen en realtime meldingen versturen via productieklare REST-API's.

API-sleutels ophalen
Live docs-workbench — fragmenten worden bijgewerkt terwijl je typt

Overzicht & eindpunten

4 eindpunten
Webhooks

Webhooks-overzicht & handtekeningverificatie

Verifieer X-Webhook-Signature als HMAC-SHA256 van de exacte onbewerkte aanvraaginhoud met uw abonnementsgeheim. Vergelijk in constante tijd en verwerk gebeurtenissen idempotent.

Handtekening-header
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Tijdstempel-header
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Replaybescherming

Controleer of X-Webhook-Id overeenkomt met de ondertekende eventId, dedupliceer gebeurtenissen en valideer de ondertekende tijdstempel volgens uw replaybeleid.

Ondersteunde gebeurtenissen

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

Verwacht antwoord

Retourneer HTTP 200 OK binnen 5.000 ms om ontvangst te bevestigen

Openbare verificatiesleutel

GET /api/v1/webhooks/public-key retourneert de actieve openbare sleutel voor handtekeningverificatie

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsAPI-sleutel
Overzicht & eindpunten

Webhook-abonnement aanmaken

Registreer een HTTPS-eindpunt om HMAC-ondertekende realtime gebeurtenismeldingen te ontvangen voor pasuitgifte, updates, scans en verwijderingen.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met doel-HTTPS-URL en lijst met webhook-gebeurtenistypen-items.

Aanvraagtekst2 vereist • 5 optioneel
urlstring (HTTPS URL)
Vereist

Uw servereindpunt-URL (moet beginnen met https://, max. 2048 tekens).

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

webhook-gebeurtenistypen-waarden: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

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

Antwoordstatuscodes

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}API-sleutel
Overzicht & eindpunten

Afmelden voor Webhook

Verwijder een actief webhook-abonnement op basis van ID en stop toekomstige gebeurtenisafleveringen naar dat eindpunt.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van het te verwijderen webhook-abonnement.

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

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsAPI-sleutel
Overzicht & eindpunten

Webhook-abonnementen weergeven

Haal alle actieve webhook-abonnementen op die voor uw klantwerkruimte zijn geregistreerd.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyOpenbaar
Overzicht & eindpunten

Openbare Webhook-handtekeningsleutel ophalen

Haal de actieve openbare PEM-sleutel van Passinstance op om uitgaande webhook-handtekeningen cryptografisch te verifiëren.

Antwoordstatuscodes

Pull-gebaseerde webhooks

2 eindpunten
Webhooks

Hoe Pull-webhooks werken & beperkingen

Ontvang realtime pas- en scangebeurtenissen via uitgaande HMAC-SHA256 Push-webhooks (met exponentiële backoff en circuit breakers) of inkomende Pull-webhookpolling voor afgeschermde netwerken, plus no-code Workflows.

Push-webhook veerkracht

5 pogingen met jittered exponentiële backoff; circuit breaker opent na 10 opeenvolgende fouten

Pull-webhook polling

GET /api/v1/webhook-payload & POST /api/v1/webhook-payload/acknowledge voor privénetwerken

Workflow-triggers

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Workflow-acties

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadAPI-sleutel
Pull-gebaseerde webhooks

Wachtende pull-webhookgebeurtenissen ophalen

Haal openstaande webhook-payloads op via uitgaande HTTPS GET voor door firewall afgeschermde of privénetwerken zonder inkomende poorten te openen.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters3 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeAPI-sleutel
Pull-gebaseerde webhooks

Pull-webhookgebeurtenissen bevestigen

Bevestig verwerkte pull-webhookpayloads tot een opgegeven payload-ID zodat ze als afgeleverd worden gemarkeerd en uit de wachtrij worden verwijderd.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met de laatst verwerkte payload-ID (upTo).

Aanvraagtekst1 vereist • 1 optioneel
upTostring (UUID)
Vereist

Laatst verwerkte webhook-payload-ID; alle gebeurtenissen tot en met deze ID worden bevestigd.

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

Antwoordstatuscodes

Webhook-gebeurtenissen

4 gidsen
Webhook-gebeurtenissenUitgaande HTTP POST-webhookmelding

Sjabloongebeurtenissen (Template Events)

Uitgaande HTTP POST-webhookmeldingen wanneer een passjabloon wordt aangemaakt, bijgewerkt, gepubliceerd of verwijderd.

Sjabloon aangemaakt
POST
TEMPLATE_CREATED

Verzonden wanneer een nieuw passjabloon wordt aangemaakt

Sjabloon bijgewerkt
POST
TEMPLATE_UPDATED

Verzonden wanneer sjabloonvelden, lay-out of mechanieken worden gewijzigd

Sjabloon gepubliceerd
POST
TEMPLATE_PUBLISHED

Verzonden wanneer een concept wordt gepubliceerd naar actieve passen

Sjabloon verwijderd
POST
TEMPLATE_DELETED

Verzonden wanneer sjabloonverwijdering en wallet-intrekking starten

Webhook-gebeurtenissenUitgaande HTTP POST-webhookmelding

Pasgebeurtenissen (Pass Events)

Uitgaande HTTP POST-webhookmeldingen voor elke fase van de paslevenscyclus, van uitgifte tot verwijdering van het apparaat.

Pas aangemaakt
POST
PASS_CREATED

Direct verzonden wanneer een nieuwe pas wordt uitgegeven via de REST API of PassFlow

Pas bijgewerkt
POST
PASS_UPDATED

Verzonden wanneer pasattributen, spaarpunten, niveau of saldo wijzigen

Pas ongeldig verklaard
POST
PASS_VOIDED

Verzonden wanneer een pas ongeldig wordt gemaakt in Apple Wallet & Google Wallet

Eerste pasdownload
POST
PASS_FIRST_DOWNLOAD

Verzonden de eerste keer dat een klant de pas claimt of downloadt

Pas gedownload
POST
PASS_DOWNLOADED

Verzonden bij elke volgende download van het paspakket of Google Wallet-link

Pas verwijderd van apparaat
POST
PASS_REMOVED

Verzonden wanneer de klant de pas verwijdert uit Apple Wallet of Google Wallet

Webhook-gebeurtenissenUitgaande HTTP POST-webhookmelding

Scangebeurtenissen (Scan Events)

Uitgaande HTTP POST-webhookmeldingen in realtime telkens wanneer een pasbarcode of NFC-pas wordt gescand en gevalideerd.

Passcan aangemaakt
POST
APP_SCAN_CREATED

Verzonden wanneer POST /api/v1/scans of een scanner een scan registreert

Scanresultaat-metadata

Bevat passId, serialNumber, templateId, configId, validatiebeslissing en saldowijziging

Aflevergarantie

At-least-once HTTPS POST-aflevering met X-Webhook-Id en X-Webhook-Signature headers

Pull-wachtrijcompatibiliteit

Ook beschikbaar via GET /api/v1/webhook-payload voor kassasystemen achter een firewall

Webhook-gebeurtenissenUitgaande HTTP POST-webhookmelding

Berichtgebeurtenissen & statusreferentie (Message Events)

Uitgaande HTTP POST-webhookmeldingen en afleverstatuscodes voor wallet-pushmeldingen, e-mails en sms-berichten.

Bericht verzonden
POST
MESSAGE_SENTNOTIFICATION_SENT

Verzonden wanneer een pasbericht of pushmelding wordt verstuurd

Aflevering mislukt
POST
MESSAGE_FAILED

Verzonden wanneer een uitgaande e-mail, sms of pushmelding mislukt

Berichtstatusreferentie

QUEUED -> SENT -> DELIVERED (of FAILED / BOUNCED met diagnostische code)

Idempotente correlatie

Koppel eventId en passId in uw webhook-consumer om herhaalde afleveringen te ontdubbelen