Skip to content
Riferimento API REST e SDK

Documentazione per sviluppatori Passinstance

Crea integrazioni su larga scala per Apple Wallet (.pkpass) e Google Wallet. Emetti, aggiorna, scansiona e invia notifiche in tempo reale tramite API REST pronte per la produzione.

Ottieni chiavi API
Workbench live — gli snippet si aggiornano mentre digiti

Panoramica ed endpoint

4 endpoint
Webhook

Panoramica Webhook e verifica della firma

Verifica X-Webhook-Signature come HMAC-SHA256 del corpo originale esatto della richiesta con il segreto della sottoscrizione. Usa un confronto a tempo costante ed elabora gli eventi in modo idempotente.

Intestazione firma
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Intestazione timestamp
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Protezione dai replay

Verifica che X-Webhook-Id corrisponda a eventId firmato, deduplica gli eventi e convalida il timestamp firmato secondo la tua politica di replay.

Eventi supportati

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

Risposta attesa

Restituisci HTTP 200 OK entro 5.000 ms per confermare la ricezione

Chiave pubblica di verifica

GET /api/v1/webhooks/public-key restituisce la chiave pubblica attiva per la verifica delle firme

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsChiave API
Panoramica ed endpoint

Crea sottoscrizione webhook

Registra un endpoint HTTPS per ricevere notifiche di eventi in tempo reale firmate HMAC per emissione, aggiornamento, scansione e disinstallazione pass.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1

Payload della richiesta contenente URL HTTPS di destinazione ed elenco di elementi tipi di evento webhook.

Corpo della richiesta2 obbligatori • 5 opzionali
urlstring (HTTPS URL)
Obbligatorio

URL del tuo server (deve iniziare con https://, max 2048 caratteri).

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

Valori tipi di evento webhook: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

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

Codici di stato della risposta

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}Chiave API
Panoramica ed endpoint

Annulla sottoscrizione Webhook

Elimina una sottoscrizione webhook attiva tramite il suo ID e interrompi l'invio di eventi futuri a quell'endpoint.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1
Parametri di percorso1 obbligatori
idstring (UUID)
Obbligatorio

UUID della sottoscrizione webhook da rimuovere.

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

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsChiave API
Panoramica ed endpoint

Elenca sottoscrizioni webhook

Recupera tutte le sottoscrizioni webhook attive registrate per il tuo workspace cliente.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyPubblico
Panoramica ed endpoint

Ottieni chiave pubblica firma Webhook

Ottieni la chiave pubblica PEM attiva di Passinstance per verificare crittograficamente le firme dei webhook in uscita.

Codici di stato della risposta

Webhook basati su Pull

2 endpoint
Webhook

Come funzionano i Pull Webhook e relative limitazioni

Ricevi eventi di pass e scansioni in tempo reale tramite webhook Push firmati HMAC-SHA256 (con backoff esponenziale e circuit breaker) o polling Pull Webhook per reti protette da firewall, oltre a Workflow no-code.

Resilienza Push Webhook

5 tentativi con backoff esponenziale con jitter; il circuit breaker si apre dopo 10 errori consecutivi

Polling Pull Webhook

GET /api/v1/webhook-payload e POST /api/v1/webhook-payload/acknowledge per reti private

Trigger Workflow

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Azioni Workflow

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadChiave API
Webhook basati su Pull

Interroga gli eventi pull-webhook in coda

Recupera i payload degli eventi webhook in attesa tramite HTTPS GET in uscita per reti private o protette da firewall senza esporre porte in ingresso.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1
Parametri di query3 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeChiave API
Webhook basati su Pull

Conferma ricezione eventi pull-webhook

Conferma i payload pull-webhook elaborati fino a un ID specifico in modo che siano contrassegnati come consegnati e rimossi dalla coda.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1

Payload della richiesta che specifica l'ID limite superiore elaborato (upTo).

Corpo della richiesta1 obbligatori • 1 opzionali
upTostring (UUID)
Obbligatorio

Ultimo ID payload webhook elaborato; tutti gli eventi fino a questo ID vengono confermati.

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

Codici di stato della risposta

Eventi Webhook

4 guide
Eventi WebhookNotifica Webhook HTTP POST in uscita

Eventi modello (Template Events)

Notifiche webhook HTTP POST inviate quando un modello di pass viene creato, aggiornato, pubblicato o eliminato.

Modello creato
POST
TEMPLATE_CREATED

Generato alla creazione di un nuovo modello di pass

Modello aggiornato
POST
TEMPLATE_UPDATED

Generato alla modifica di campi, layout o meccaniche del modello

Modello pubblicato
POST
TEMPLATE_PUBLISHED

Generato alla pubblicazione di una bozza sui pass attivi

Modello eliminato
POST
TEMPLATE_DELETED

Generato all'avvio dell'eliminazione del modello e revoca nei wallet

Eventi WebhookNotifica Webhook HTTP POST in uscita

Eventi pass (Pass Events)

Notifiche webhook HTTP POST che tracciano ogni fase del ciclo di vita di un pass dalla creazione alla rimozione dal dispositivo.

Pass creato
POST
PASS_CREATED

Generato immediatamente quando un nuovo pass viene emesso tramite API REST o PassFlow

Pass aggiornato
POST
PASS_UPDATED

Generato quando attributi, punti fedeltà, livello o saldo del pass cambiano

Pass annullato
POST
PASS_VOIDED

Generato quando un pass viene annullato o disattivato su Apple Wallet e Google Wallet

Primo download del pass
POST
PASS_FIRST_DOWNLOAD

Generato la prima volta che un cliente riscatta o scarica il pass

Pass scaricato
POST
PASS_DOWNLOADED

Generato a ogni download successivo del pacchetto o link Google Wallet

Pass rimosso dal dispositivo
POST
PASS_REMOVED

Generato quando il cliente elimina il pass da Apple Wallet o Google Wallet

Eventi WebhookNotifica Webhook HTTP POST in uscita

Eventi di scansione (Scan Events)

Notifiche webhook HTTP POST inviate in tempo reale ogni volta che il codice a barre o NFC di un pass viene scansionato e convalidato.

Scansione pass creata
POST
APP_SCAN_CREATED

Generato quando POST /api/v1/scans o uno scanner registra una scansione

Metadati esito scansione

Include passId, serialNumber, templateId, configId, decisione di validazione e variazione saldo

Garanzia di consegna

Consegna HTTPS POST at-least-once con header X-Webhook-Id e X-Webhook-Signature

Compatibilità coda Pull

Disponibile anche tramite GET /api/v1/webhook-payload per POS protetti da firewall

Eventi WebhookNotifica Webhook HTTP POST in uscita

Eventi messaggio e riferimento stati (Message Events)

Notifiche webhook HTTP POST e codici di stato di consegna per notifiche push wallet, invii email e SMS.

Messaggio inviato
POST
MESSAGE_SENTNOTIFICATION_SENT

Generato all'invio di un messaggio o aggiornamento push

Consegna fallita
POST
MESSAGE_FAILED

Generato quando un'email, SMS o notifica push non viene recapitata

Riferimento stati messaggio

QUEUED -> SENT -> DELIVERED (o FAILED / BOUNCED con codice diagnostico)

Correlazione idempotente

Abbina eventId e passId nel consumer webhook per deduplicare eventuali ritentativi