Skip to content
Guide du centre d'aide · API développeur
5 min de lectureVérifié 2026-11-16

Webhooks & événements

Souscrivez aux rappels en temps réel (ajout, suppression, scan, mise à jour) et vérifiez les signatures HMAC-SHA256.

Dans ce guide

Aperçu

Passinstance offre une architecture webhook bi-mode administrable via /api/v1/webhooks/subscriptions (ou sous Paramètres de l'espace -> Développeur -> Webhooks à /settings/workspace/developer/webhooks) afin de synchroniser les événements du cycle de vie des passes avec n'importe quelle infrastructure :

  1. 1
    Push Webhooks (Push Webhook Dispatcher) : Rappels HTTPS POST sortants en temps réel signés avec un secret HMAC-SHA256 propre à chaque abonnement (X-Webhook-Signature), protégés contre les attaques SSRF, dotés de nouvelles tentatives à backoff exponentiel avec gigue (DEFAULT_MAX_RETRIES = 5) et d'un coupe-circuit par point d'entrée (CIRCUIT_BREAKER_THRESHOLD = 10 échecs consécutifs, délai de refroidissement 30 minutes).
  2. 2
    Pull Webhooks (Webhook Pull API) : Une API d'interrogation de file sans préfixe (GET /webhook-payload / GET /api/v3/webhook-payload et POST /webhook-payload/acknowledge / POST /api/v3/webhook-payload/acknowledge) conçue pour les serveurs ERP sur site ou protégés par pare-feu ne pouvant pas exposer de port HTTPS entrant public.

Important : Vérifiez toujours l'en-tête X-Webhook-Signature sur les octets bruts non analysés du corps HTTP à l'aide de crypto.timingSafeEqual avant de parser le JSON ou d'exécuter toute logique métier. Resérialiser un objet JSON analysé modifie les espaces ou l'ordre des clés et invalide l'empreinte HMAC.

Architecture webhook bi-mode

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
DISTRIBUTION WEBHOOK BI-MODE PUSH & PULL
ÉTAPE 01 Bus d'événements Passinstance
ÉTAPE 02 Mode 1 : Push Webhook Delivery (Push Webhook Dispatcher)
1
Valider URL cible (Webhook URL Validator : bloque IP privées / SSRF)
2
Signer la charge (Webhook Signing EngineX-Webhook-Signature: sha256=<hmac>)
3
POST vers HTTPS client (User-Agent: Passinstance-Webhook/2.0)
4
Sur 5xx / Timeout (10s) : jusqu'à 5 tentatives avec backoff exponentiel +-- 5. Après 10 échecs consécutifs : ouverture du coupe-circuit (pause 30 min)
ÉTAPE 03 Mode 2 : Pull Webhook Queue (Webhook Pull API)
-- 1. Empiler la charge utile dans le tampon pull du locataire -- 2. Le client derrière pare-feu interroge : GET/webhook-payload?webhookId=...&limit=100&since=... +-- 3. Le client acquitte le curseur traité : POST/webhook-payload/acknowledge { upTo: "wpl_01hxyz...", webhookId }

Points d'entrée de gestion des abonnements (Webhooks API)

MéthodePoint d'entréeRôle
GET/api/v1/webhooksRécupère la vue d'ensemble des webhooks de l'espace et les statistiques d'envoi.
GET / POST/api/v1/webhooks/subscriptionsListe ou crée des abonnements webhook sortants (events, url HTTPS, filtres optionnels).
PATCH/api/v1/webhooks/subscriptions/:idMet à jour les événements souscrits, l'état actif ou l'URL cible.
DELETE/api/v1/webhooks/subscriptions/:idSupprime un abonnement webhook.
POST/api/v1/webhooks/subscriptions/:id/regenerate-secretFait tourner le secret de signature HMAC-SHA256 d'un abonnement.
POST/api/v1/webhooks/subscriptions/:id/testEnvoie une requête de diagnostic et réinitialise le coupe-circuit.
GET/api/v1/webhooks/eventsRetourne les métadonnées canoniques WebhookEventType et des exemples de charges utiles.
GET/api/v1/webhooks/historyInspecte l'historique des envois et journaux de tentatives (/api/v1/webhooks/history/:eventHistoryId/attempts).

1. Types d'événements canoniques & correspondance Passinstance database webhook event

WebhookEventRegistry normalise 31 valeurs internes du domaine Passinstance database webhook event en 11 chaînes canoniques WebhookEventType émises vers les récepteurs webhook (les anciens alias à points tels que pass.created sont également convertis proprement lors de la création de l'abonnement) :

Type canonique WebhookEventTypeValeurs webhook event mappéesCas d'usage principal
pass_createdPASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASEDSynchroniser passId, externalId et le lien intelligent dans la fiche contact CRM.
pass_updatedPASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOGRefléter un changement de palier fidélité, externalId ou solde prépayé dans l'ERP.
pass_voidedPASS_VOIDED, PASS_REVOKED, PASS_DELETEDMarquer un bon d'achat comme utilisé ou révoqué en base e-commerce.
first_pushnotification_registeredPUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOADDéclencher un avantage de bienvenue lors de la toute première installation.
pushnotification_registeredPUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADEDSuivre l'adoption multi-appareils (ex. iPhone + Apple Watch jumelée).
pushnotification_unregisteredPUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVEDMettre à jour le statut de désinstallation dans le CRM ou lancer une relance.
pass_template_createdTEMPLATE_CREATEDProvisionner les métadonnées de campagne correspondantes dans des systèmes externes.
pass_template_updatedTEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATEDActualiser le cache des champs de modèles ou réglages bundleId.
app_scan_createdAPP_SCAN_CREATED, LOCATION_ENTEREDEnregistrer une visite boutique, un cumul fidélité, une entrée géolocalisée ou un check-in billet en BI.
message_sentMESSAGE_SENT, NOTIFICATION_SENTConsigner l'envoi d'une alerte écran verrouillé ou d'une campagne dans la chronologie client.
message_failedMESSAGE_FAILEDAlerter l'exploitation ou déclencher un canal de secours SMS/e-mail.

En-têtes HTTP Push sortants

Chaque requête POST sortante issue de Push Webhook Dispatcher contient :

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

Vérification de signature HMAC-SHA256 (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);
}

Protection SSRF, nouvelles tentatives & coupe-circuit

  • Validation SSRF des cibles (Webhook URL Validator) : Interdit l'enregistrement et la livraison vers les boucles locales (127.0.0.0/8, ::1), réseaux privés RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), adresses link-local et IP de métadonnées cloud (169.254.169.254).
  • Backoff exponentiel : Les réponses non-2xx ou dépassements de délai (10s, DEFAULT_TIMEOUT_MS) sont réessayés jusqu'à 5 fois (DEFAULT_MAX_RETRIES) avec backoff exponentiel et gigue.
  • Coupe-circuit : Après 10 échecs de livraison consécutifs (CIRCUIT_BREAKER_THRESHOLD), circuitOpenedAt ouvre le coupe-circuit pour une période de refroidissement de 30 minutes (CIRCUIT_BREAKER_COOLDOWN_MS) avant une nouvelle tentative.

2. Pull Webhooks (Webhook Pull API)

Lorsque votre serveur fonctionne derrière un pare-feu d'entreprise ou un NAT sans port HTTPS public entrant, configurez un Pull Webhook et interrogez la file d'événements par requêtes HTTPS sortantes via GET /webhook-payload (ou l'alias GET /api/v3/webhook-payload) :

Interroger les charges utiles en attente (GET /webhook-payload)

GET /webhook-payload?webhookId=whk_01hxyz5512&limit=100&since=2026-11-16T08:00:00.000Z En-tête : x-api-key: pi_live_... (défaut 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
}

Acquitter les événements traités (POST /webhook-payload/acknowledge)

Une fois le lot persisté par votre worker, acquittez jusqu'au dernier ID traité (POST /webhook-payload/acknowledge ou POST /api/v3/webhook-payload/acknowledge) afin de retirer ces événements de la file :

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

Consultez Tests & débogage et la Référence API Webhooks pour le détail des schémas de charges utiles.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.