Skip to content
Guida del Centro assistenza · API per sviluppatori
5 min di letturaVerificato 2026-11-16

Webhook ed eventi

Ricevi callback in tempo reale (aggiunto, rimosso, scansionato, aggiornato) e verifica firme HMAC-SHA256.

In questa guida

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. 1
    Webhook Push (Push Webhook Dispatcher): Callback HTTPS POST in 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 = 10 errori consecutivi, raffreddamento di 30 minuti).
  2. 2
    Webhook Pull (Webhook Pull API): Un'API di polling su coda priva di prefisso (GET /webhook-payload / GET /api/v3/webhook-payload e POST /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-Signature rispetto ai byte grezzi non analizzati del corpo della richiesta HTTP utilizzando crypto.timingSafeEqual prima 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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CONSEGNA WEBHOOK DUAL-MODE PUSH E PULL
FASE 01 Bus eventi Passinstance
FASE 02 Modalità 1: Consegna Push Webhook (Push Webhook Dispatcher)
1
Valida URL target (Webhook URL Validator: blocca IP privati/SSRF)
2
Firma payload (Webhook Signing EngineX-Webhook-Signature: sha256=<hmac>)
3
POST verso endpoint HTTPS cliente (User-Agent: Passinstance-Webhook/2.0)
4
Su 5xx / timeout (10s default): Riprova fino a 5x con exponential backoff +-- 5. Su 10 errori consecutivi: Attiva Circuit Breaker (30 minuti di pausa)
FASE 03 Modalità 2: Coda Pull Webhook (Webhook Pull API)
-- 1. Accoda payload evento nel buffer pull del tenant -- 2. Il client dietro firewall interroga: GET/webhook-payload?webhookId=...&limit=100&since=... +-- 3. Il client conferma il cursore elaborato: POST/webhook-payload/acknowledge { upTo: "wpl_01hxyz...", webhookId }

Endpoint di gestione delle sottoscrizioni (Webhooks API)

MetodoEndpointScopo
GET/api/v1/webhooksRecupera la panoramica webhook del workspace e le statistiche di consegna.
GET / POST/api/v1/webhooks/subscriptionsElenca o crea sottoscrizioni webhook in uscita (events, url HTTPS, filtri opzionali).
PATCH/api/v1/webhooks/subscriptions/:idAggiorna gli eventi sottoscritti, lo stato attivo o l'URL endpoint di destinazione.
DELETE/api/v1/webhooks/subscriptions/:idElimina una sottoscrizione webhook.
POST/api/v1/webhooks/subscriptions/:id/regenerate-secretRuota il segreto di firma HMAC-SHA256 di una sottoscrizione.
POST/api/v1/webhooks/subscriptions/:id/testInvia una consegna diagnostica di prova e azzera lo stato del circuit breaker.
GET/api/v1/webhooks/eventsRestituisce i metadati canonici WebhookEventType e i payload di esempio.
GET/api/v1/webhooks/historyIspeziona 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 canonicoValori webhook event mappatiCaso d'uso principale
pass_createdPASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASEDSincronizza passId, externalId e smart link sul record contatto nel CRM.
pass_updatedPASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOGRispecchia livello fedeltà, externalId o saldo prepagato aggiornato nell'ERP esterno.
pass_voidedPASS_VOIDED, PASS_REVOKED, PASS_DELETEDContrassegna il codice voucher come speso o revocato nel database ordini e-commerce.
first_pushnotification_registeredPUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOADAvvia il workflow bonus di benvenuto quando il pass viene installato per la prima volta.
pushnotification_registeredPUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADEDTraccia l'adozione su più dispositivi (es. iPhone + Apple Watch abbinato).
pushnotification_unregisteredPUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVEDAggiorna lo stato disinstallazione/opt-out nel CRM o avvia sequenze di recupero clienti.
pass_template_createdTEMPLATE_CREATEDPredispone i metadati di campagna corrispondenti nei sistemi esterni.
pass_template_updatedTEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATEDAggiorna la cache di mappatura campi dei modelli o delle impostazioni bundleId.
app_scan_createdAPP_SCAN_CREATED, LOCATION_ENTEREDRegistra visite in negozio, accumuli fedeltà, ingressi geofence o check-in biglietti nella BI.
message_sentMESSAGE_SENT, NOTIFICATION_SENTRegistra nella timeline cliente i touchpoint di push in schermata di blocco o invio campagne.
message_failedMESSAGE_FAILEDAvvisa 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:

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

Verifica della firma 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);
}

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-2xx o timeout di 10s (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), circuitOpenedAt apre 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)

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
}

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:

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

Consulti Test e debug e il Riferimento API Webhook per gli schemi completi dei payload.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.