Skip to content
Référence API REST & SDKs

Documentation Développeur Passinstance

Créez des intégrations Apple Wallet (.pkpass) et Google Wallet à grande échelle. Émettez, mettez à jour, validez et diffusez des notifications en direct via des API REST prêtes pour la production.

Obtenir les clés API
Atelier docs en direct — les extraits se mettent à jour en temps réel

Aperçu et points de terminaison

4 points de terminaison
Webhooks

Aperçu des Webhooks et vérification des signatures

Vérifiez X-Webhook-Signature comme HMAC-SHA256 du corps brut exact de la requête avec le secret de votre abonnement. Utilisez une comparaison en temps constant et un traitement idempotent des événements.

En-tête de signature
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
En-tête d'horodatage
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Protection contre le rejeu

Vérifiez que X-Webhook-Id correspond à eventId signé, dédupliquez les événements et validez l'horodatage signé selon votre politique de rejeu.

Événements pris en charge

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

Réponse attendue

Renvoyer HTTP 200 OK sous 5 000 ms pour accuser réception

Découverte de la clé publique

GET /api/v1/webhooks/public-key renvoie la clé publique active pour la vérification des signatures

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsClé API
Aperçu et points de terminaison

Créer un abonnement webhook

Enregistrer un point de terminaison HTTPS pour recevoir en temps réel les notifications d'événements signées HMAC (émission, mise à jour, scan, désinstallation).

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1

Charge utile de requête contenant l'URL HTTPS cible et le tableau d'événements types d'événements webhook.

Corps de la requête2 requis • 5 optionnel(s)
urlstring (HTTPS URL)
Requis

URL de votre serveur (doit commencer par https://, 2048 car. max).

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

Valeurs types d'événements webhook : PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

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

Codes de statut de réponse

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}Clé API
Aperçu et points de terminaison

Se désabonner d'un Webhook

Supprimez un abonnement webhook actif via son identifiant et arrêtez l'envoi d'événements futurs vers cette URL.

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1
Paramètres de chemin1 requis
idstring (UUID)
Requis

UUID de l'abonnement webhook à supprimer.

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

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsClé API
Aperçu et points de terminaison

Lister les abonnements webhook

Récupérer tous les abonnements webhook actifs enregistrés pour votre espace client.

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1

Codes de statut de réponse

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyPublic
Aperçu et points de terminaison

Obtenir la clé publique de signature Webhook

Récupérez la clé publique PEM active de Passinstance pour vérifier cryptographiquement les signatures des webhooks sortants.

Codes de statut de réponse

Webhooks en mode Pull

2 points de terminaison
Webhooks

Fonctionnement et limites des Webhooks en mode Pull

Consommez les événements de cartes et de scans en temps réel via webhooks Push signés HMAC-SHA256 (avec backoff exponentiel et disjoncteur) ou via interrogation Pull Webhook pour environnements filtrés, ainsi que des Workflows sans code.

Résilience Push Webhook

5 tentatives avec backoff exponentiel avec gigue ; disjoncteur ouvert après 10 échecs consécutifs

Interrogation Pull Webhook

GET /api/v1/webhook-payload & POST /api/v1/webhook-payload/acknowledge pour réseaux privés

Déclencheurs Workflow

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Actions Workflow

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadClé API
Webhooks en mode Pull

Interroger la file des événements pull-webhook

Récupérer les événements webhook en attente via HTTPS GET sortant pour les réseaux privés ou filtrés par pare-feu sans ouvrir de port entrant.

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1
Paramètres de requête3 optionnel(s)

Codes de statut de réponse

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeClé API
Webhooks en mode Pull

Acquitter les événements pull-webhook

Acquitter les charges utiles pull-webhook traitées jusqu'à un ID donné pour les marquer livrées et les retirer de la file de scrutation.

En-têtes1 requis
X-API-Keystring
Requis

Clé API secrète de l'espace de travail (pi_live_... ou pi_test_...). Vous pouvez également envoyer Authorization: ApiKey <key>.

Exemple : pi_live_98a7b6c5d4e3f2a1

Charge utile de requête spécifiant l'ID borne supérieure traité (upTo).

Corps de la requête1 requis • 1 optionnel(s)
upTostring (UUID)
Requis

Dernier ID de charge utile traité ; tous les événements jusqu'à cet ID sont acquittés.

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

Codes de statut de réponse

Événements Webhook

4 guides
Événements WebhookNotification Webhook HTTP POST sortante

Événements de modèle (Template Events)

Notifications webhook HTTP POST envoyées lorsqu'un modèle de carte est créé, modifié, publié ou supprimé.

Modèle créé
POST
TEMPLATE_CREATED

Émis lors de la création d'un nouveau modèle de carte

Modèle mis à jour
POST
TEMPLATE_UPDATED

Émis lors de la modification des champs, de la mise en page ou des mécaniques

Modèle publié
POST
TEMPLATE_PUBLISHED

Émis lors de la publication d'un brouillon vers les cartes actives

Modèle supprimé
POST
TEMPLATE_DELETED

Émis lors du lancement de la suppression du modèle et de la révocation wallet

Événements WebhookNotification Webhook HTTP POST sortante

Événements de carte (Pass Events)

Notifications webhook HTTP POST suivant chaque étape du cycle de vie d'une carte, de l'émission au retrait de l'appareil.

Carte créée
POST
PASS_CREATED

Émis immédiatement lorsqu'une nouvelle carte est créée via l'API REST ou PassFlow

Carte mise à jour
POST
PASS_UPDATED

Émis lorsque les attributs, points de fidélité, palier ou solde de la carte changent

Carte annulée
POST
PASS_VOIDED

Émis lorsqu'une carte est annulée ou désactivée dans Apple Wallet et Google Wallet

Premier téléchargement
POST
PASS_FIRST_DOWNLOAD

Émis la première fois qu'un client récupère ou télécharge la carte

Carte téléchargée
POST
PASS_DOWNLOADED

Émis lors de chaque téléchargement ultérieur du fichier ou lien Google Wallet

Carte retirée de l'appareil
POST
PASS_REMOVED

Émis lorsque le client supprime la carte d'Apple Wallet ou de Google Wallet

Événements WebhookNotification Webhook HTTP POST sortante

Événements de scan (Scan Events)

Notifications webhook HTTP POST émises en temps réel dès qu'un code-barres ou une carte NFC est scanné et validé.

Scan de carte créé
POST
APP_SCAN_CREATED

Émis lorsque POST /api/v1/scans ou un scanner appairé enregistre un scan

Métadonnées du scan

Inclut passId, serialNumber, templateId, configId, décision de validation et variation de solde

Garantie de livraison

Livraison HTTPS POST au moins une fois avec en-têtes X-Webhook-Id et X-Webhook-Signature

Compatibilité file Pull

Également disponible via GET /api/v1/webhook-payload pour les systèmes de caisse derrière pare-feu

Événements WebhookNotification Webhook HTTP POST sortante

Événements de message et référence des statuts (Message Events)

Notifications webhook HTTP POST et codes de statut de livraison pour les notifications push wallet, e-mails et SMS.

Message envoyé
POST
MESSAGE_SENTNOTIFICATION_SENT

Émis lors de l'envoi d'un message ou d'une notification push

Échec de livraison
POST
MESSAGE_FAILED

Émis lorsqu'un e-mail, SMS ou push sortant échoue à la livraison

Référence des statuts de message

QUEUED -> SENT -> DELIVERED (ou FAILED / BOUNCED avec code de diagnostic)

Corrélation idempotente

Associez eventId et passId dans votre consommateur webhook pour dédupliquer les renvois