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
Push Webhooks (
Push Webhook Dispatcher) : Rappels HTTPSPOSTsortants 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 refroidissement30minutes). -
2
Pull Webhooks (
Webhook Pull API) : Une API d'interrogation de file sans préfixe (GET /webhook-payload/GET /api/v3/webhook-payloadetPOST /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-Signaturesur les octets bruts non analysés du corps HTTP à l'aide decrypto.timingSafeEqualavant 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
Points d'entrée de gestion des abonnements (Webhooks API)
| Méthode | Point d'entrée | Rôle |
|---|---|---|
| GET | /api/v1/webhooks | Récupère la vue d'ensemble des webhooks de l'espace et les statistiques d'envoi. |
GET / POST | /api/v1/webhooks/subscriptions | Liste ou crée des abonnements webhook sortants (events, url HTTPS, filtres optionnels). |
| PATCH | /api/v1/webhooks/subscriptions/:id | Met à jour les événements souscrits, l'état actif ou l'URL cible. |
| DELETE | /api/v1/webhooks/subscriptions/:id | Supprime un abonnement webhook. |
| POST | /api/v1/webhooks/subscriptions/:id/regenerate-secret | Fait tourner le secret de signature HMAC-SHA256 d'un abonnement. |
| POST | /api/v1/webhooks/subscriptions/:id/test | Envoie une requête de diagnostic et réinitialise le coupe-circuit. |
| GET | /api/v1/webhooks/events | Retourne les métadonnées canoniques WebhookEventType et des exemples de charges utiles. |
| GET | /api/v1/webhooks/history | Inspecte 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 WebhookEventType | Valeurs webhook event mappées | Cas d'usage principal |
|---|---|---|
pass_created | PASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASED | Synchroniser passId, externalId et le lien intelligent dans la fiche contact CRM. |
pass_updated | PASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOG | Refléter un changement de palier fidélité, externalId ou solde prépayé dans l'ERP. |
pass_voided | PASS_VOIDED, PASS_REVOKED, PASS_DELETED | Marquer un bon d'achat comme utilisé ou révoqué en base e-commerce. |
first_pushnotification_registered | PUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOAD | Déclencher un avantage de bienvenue lors de la toute première installation. |
pushnotification_registered | PUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADED | Suivre l'adoption multi-appareils (ex. iPhone + Apple Watch jumelée). |
pushnotification_unregistered | PUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVED | Mettre à jour le statut de désinstallation dans le CRM ou lancer une relance. |
pass_template_created | TEMPLATE_CREATED | Provisionner les métadonnées de campagne correspondantes dans des systèmes externes. |
pass_template_updated | TEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATED | Actualiser le cache des champs de modèles ou réglages bundleId. |
app_scan_created | APP_SCAN_CREATED, LOCATION_ENTERED | Enregistrer une visite boutique, un cumul fidélité, une entrée géolocalisée ou un check-in billet en BI. |
message_sent | MESSAGE_SENT, NOTIFICATION_SENT | Consigner l'envoi d'une alerte écran verrouillé ou d'une campagne dans la chronologie client. |
message_failed | MESSAGE_FAILED | Alerter 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 :
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)
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-
2xxou 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),circuitOpenedAtouvre 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)
{
"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 :
{
"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.
