Panoramica
Passinstance offre un'architettura webhook dual-mode gestita tramite /api/v1/webhooks/subscriptions (oppure nella Dashboard sotto Impostazioni Workspace -> Sviluppatore -> Webhook su /settings/workspace/developer/webhooks) per sincronizzare gli eventi del ciclo di vita Wallet con qualsiasi infrastruttura:
-
1
Webhook Push (
Push Webhook Dispatcher): Callback HTTPSPOSTin uscita in tempo reale firmati con segreti HMAC-SHA256 per singola sottoscrizione (X-Webhook-Signature), protetti da validazione target anti-SSRF, nuovi tentativi automatici con exponential backoff con jitter (DEFAULT_MAX_RETRIES = 5) e un circuit breaker per endpoint (CIRCUIT_BREAKER_THRESHOLD = 10errori consecutivi, raffreddamento di30minuti). -
2
Webhook Pull (
Webhook Pull API): Un'API di polling su coda priva di prefisso (GET /webhook-payload/GET /api/v3/webhook-payloadePOST /webhook-payload/acknowledge/POST /api/v3/webhook-payload/acknowledge) progettata per server ERP aziendali, on-premise o dietro firewall che non possono esporre porte HTTPS pubbliche in ingresso.
Importante: Verifichi sempre l'header
X-Webhook-Signaturerispetto ai byte grezzi non analizzati del corpo della richiesta HTTP utilizzandocrypto.timingSafeEqualprima di effettuare il parsing JSON o eseguire logica applicativa. Ri-serializzare un oggetto JSON già analizzato modifica spaziature o ordine delle chiavi e invalida il digest HMAC.
Architettura webhook dual-mode
Endpoint di gestione delle sottoscrizioni (Webhooks API)
| Metodo | Endpoint | Scopo |
|---|---|---|
| GET | /api/v1/webhooks | Recupera la panoramica webhook del workspace e le statistiche di consegna. |
GET / POST | /api/v1/webhooks/subscriptions | Elenca o crea sottoscrizioni webhook in uscita (events, url HTTPS, filtri opzionali). |
| PATCH | /api/v1/webhooks/subscriptions/:id | Aggiorna gli eventi sottoscritti, lo stato attivo o l'URL endpoint di destinazione. |
| DELETE | /api/v1/webhooks/subscriptions/:id | Elimina una sottoscrizione webhook. |
| POST | /api/v1/webhooks/subscriptions/:id/regenerate-secret | Ruota il segreto di firma HMAC-SHA256 di una sottoscrizione. |
| POST | /api/v1/webhooks/subscriptions/:id/test | Invia una consegna diagnostica di prova e azzera lo stato del circuit breaker. |
| GET | /api/v1/webhooks/events | Restituisce i metadati canonici WebhookEventType e i payload di esempio. |
| GET | /api/v1/webhooks/history | Ispeziona le consegne storiche e i log dei tentativi (/api/v1/webhooks/history/:eventHistoryId/attempts). |
1. Tipi di evento canonici e mapping Passinstance database webhook event
WebhookEventRegistry normalizza 31 valori interni di dominio Passinstance database webhook event in 11 stringhe canoniche WebhookEventType emesse ai riceventi webhook (in fase di creazione sottoscrizione vengono mappati in modo trasparente anche alias legacy con punto come pass.created):
WebhookEventType canonico | Valori webhook event mappati | Caso d'uso principale |
|---|---|---|
pass_created | PASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASED | Sincronizza passId, externalId e smart link sul record contatto nel CRM. |
pass_updated | PASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOG | Rispecchia livello fedeltà, externalId o saldo prepagato aggiornato nell'ERP esterno. |
pass_voided | PASS_VOIDED, PASS_REVOKED, PASS_DELETED | Contrassegna il codice voucher come speso o revocato nel database ordini e-commerce. |
first_pushnotification_registered | PUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOAD | Avvia il workflow bonus di benvenuto quando il pass viene installato per la prima volta. |
pushnotification_registered | PUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADED | Traccia l'adozione su più dispositivi (es. iPhone + Apple Watch abbinato). |
pushnotification_unregistered | PUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVED | Aggiorna lo stato disinstallazione/opt-out nel CRM o avvia sequenze di recupero clienti. |
pass_template_created | TEMPLATE_CREATED | Predispone i metadati di campagna corrispondenti nei sistemi esterni. |
pass_template_updated | TEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATED | Aggiorna la cache di mappatura campi dei modelli o delle impostazioni bundleId. |
app_scan_created | APP_SCAN_CREATED, LOCATION_ENTERED | Registra visite in negozio, accumuli fedeltà, ingressi geofence o check-in biglietti nella BI. |
message_sent | MESSAGE_SENT, NOTIFICATION_SENT | Registra nella timeline cliente i touchpoint di push in schermata di blocco o invio campagne. |
message_failed | MESSAGE_FAILED | Avvisa il team operativo o attiva un canale SMS/e-mail di fallback. |
Header HTTP delle richieste push in uscita
Ogni richiesta POST in uscita inviata da Push Webhook Dispatcher include:
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
Verifica della firma 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);
}
Protezione SSRF, nuovi tentativi e Circuit Breaker
-
Validazione target SSRF (
Webhook URL Validator): Rifiuta la registrazione e la consegna verso indirizzi di loopback (127.0.0.0/8,::1), reti private RFC 1918 (10.0.0.0/8,172.16.0.0/12,192.168.0.0/16), indirizzi link-local e IP di metadati cloud (169.254.169.254). -
Exponential Backoff: Risposte non-
2xxo timeout di10s(DEFAULT_TIMEOUT_MS) vengono ritentati fino a 5 volte (DEFAULT_MAX_RETRIES) con exponential backoff con jitter. -
Circuit Breaker: Dopo 10 errori di consegna consecutivi (
CIRCUIT_BREAKER_THRESHOLD),circuitOpenedAtapre il circuito per un periodo di pausa di 30 minuti (CIRCUIT_BREAKER_COOLDOWN_MS) prima di eseguire un nuovo tentativo di verifica.
2. Pull Webhook (Webhook Pull API)
Quando il proprio server opera dietro un firewall aziendale o NAT senza accesso HTTPS pubblico in ingresso, configuri un Pull Webhook e interroghi gli eventi in coda tramite HTTPS in uscita utilizzando GET /webhook-payload (oppure l'alias GET /api/v3/webhook-payload):
Polling dei payload in coda (GET /webhook-payload)
GET /webhook-payload?webhookId=whk_01hxyz5512&limit=100&since=2026-11-16T08:00:00.000Z Header: x-api-key: pi_live_... (limit predefinito 100, massimo 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
}
Conferma degli eventi elaborati (POST /webhook-payload/acknowledge)
Una volta che il proprio worker ha salvato il batch, confermi fino all'ultimo ID payload elaborato (POST /webhook-payload/acknowledge o POST /api/v3/webhook-payload/acknowledge) affinché tali eventi vengano rimossi dalla coda:
{
"webhookId": "whk_01hxyz5512",
"upTo": "wpl_01hxyz8801"
}
Consulti Test e debug e il Riferimento API Webhook per gli schemi completi dei payload.
