Skip to content
Helpcentrum-gids · Ontwikkelaars-API
4 min leestijdGecontroleerd 2026-11-16

Webhooks & gebeurtenissen

Ontvang realtime meldingen (toegevoegd, verwijderd, gescand, bijgewerkt) en verifieer HMAC-SHA256-handtekeningen.

In deze gids

Overzicht

Passinstance biedt een dual-mode webhook-architectuur beheerd via /api/v1/webhooks/subscriptions (of in Werkruimte-instellingen -> Ontwikkelaars -> Webhooks op /settings/workspace/developer/webhooks) zodat u Wallet-levenscyclusgebeurtenissen met elke infrastructuur kunt synchroniseren:

  1. 1
    Push Webhooks (Push Webhook Dispatcher): Realtime uitgaande HTTPS POST-callbacks ondertekend met een eigen HMAC-SHA256-geheim per abonnement (X-Webhook-Signature), beschermd door SSRF-doelvalidatie, automatische herpogingen met jitter en exponentiële wachttijd (DEFAULT_MAX_RETRIES = 5) en een circuit breaker per endpoint (CIRCUIT_BREAKER_THRESHOLD = 10 opeenvolgende fouten, 30 minuten afkoelperiode).
  2. 2
    Pull Webhooks (Webhook Pull API): Een prefixvrije inkomende polling-wachtrij-API (GET /webhook-payload / GET /api/v3/webhook-payload en POST /webhook-payload/acknowledge / POST /api/v3/webhook-payload/acknowledge) voor on-premise, lokaal draaiende of achter firewalls afgeschermde ERP-servers zonder openbare HTTPS-poort.

Belangrijk: Verifieer de header X-Webhook-Signature altijd tegen de ruwe, ongeparste HTTP-requestbodybytes met crypto.timingSafeEqual voordat u JSON parseert of bedrijfslogica uitvoert. Opnieuw serialiseren van een geparst JSON-object wijzigt witruimte of sleutelvolgorde en maakt de HMAC-handtekening ongeldig.

Dual-mode webhook-architectuur

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
DUAL-MODE PUSH & PULL WEBHOOK-LEVERING
FASE 01 Passinstance Event Bus
FASE 02 Modus 1: Push Webhook Delivery (Push Webhook Dispatcher)
1
Valideer Doel-URL (Webhook URL Validator: blokkeer private/SSRF IPs)
2
Onderteken Payload (Webhook Signing EngineX-Webhook-Signature: sha256=<hmac>)
3
POST naar HTTPS-endpoint klant (User-Agent: Passinstance-Webhook/2.0)
4
Bij 5xx / Timeout (10s stand.): Herhaal max 5x met jitter & backoff +-- 5. Na 10 opeenvolgende fouten: Open Circuit Breaker (30 min afkoelperiode)
FASE 03 Modus 2: Pull Webhook-wachtrij (Webhook Pull API)
-- 1. Plaats gebeurtenispayload in pullbuffer van tenant -- 2. Afgeschermde client pollt: GET/webhook-payload?webhookId=...&limit=100&since=... +-- 3. Client bevestigt verwerkte cursor: POST/webhook-payload/acknowledge { upTo: "wpl_01hxyz...", webhookId }

Endpoints voor abonnementsbeheer (Webhooks API)

MethodeEndpointDoel
GET/api/v1/webhooksHaalt werkruimte-webhookoverzicht en afleverstatistieken op.
GET / POST/api/v1/webhooks/subscriptionsToont of maakt uitgaande webhook-abonnementen (events, HTTPS url, optionele filters).
PATCH/api/v1/webhooks/subscriptions/:idWerkt geabonneerde gebeurtenissen, actieve status of doel-URL bij.
DELETE/api/v1/webhooks/subscriptions/:idVerwijdert een webhook-abonnement.
POST/api/v1/webhooks/subscriptions/:id/regenerate-secretRoteert het HMAC-SHA256-ondertekeningsgeheim van een abonnement.
POST/api/v1/webhooks/subscriptions/:id/testVerzendt een diagnostische testaanvraag en reset de circuit-breakerstatus.
GET/api/v1/webhooks/eventsRetourneert canonieke WebhookEventType-metadata en voorbeeldpayloads.
GET/api/v1/webhooks/historyInspecteert aflevergeschiedenis en afzonderlijke pogingslogboeken (/api/v1/webhooks/history/:eventHistoryId/attempts).

1. Canonieke gebeurtenistypen & Passinstance database webhook event-koppeling

WebhookEventRegistry normaliseert 31 interne Passinstance database webhook event-domeinwaarden naar 11 canonieke WebhookEventType-tekenreeksen die naar webhookontvangers worden verstuurd (verouderde notaties met punten zoals pass.created worden bij het aanmaken van het abonnement eveneens netjes omgezet):

Canoniek WebhookEventTypeGekoppelde webhook event-waardenBelangrijkste toepassing
pass_createdPASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASEDSynchroniseer passId, externalId en slimme link terug naar CRM-contactrecord.
pass_updatedPASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOGSpiegel bijgewerkt loyaliteitsniveau, externalId of prepaidtegoed in extern ERP.
pass_voidedPASS_VOIDED, PASS_REVOKED, PASS_DELETEDMarkeer waardeboncode als gebruikt of ingetrokken in e-commerce checkout-database.
first_pushnotification_registeredPUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOADStart welkomstbonus-workflow bij eerste Wallet-installatie.
pushnotification_registeredPUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADEDVolg adoptie op meerdere apparaten (bijv. iPhone + gekoppelde Apple Watch).
pushnotification_unregisteredPUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVEDWerk CRM-verwijder-/opt-outstatus bij of start een terugwinactie.
pass_template_createdTEMPLATE_CREATEDRicht bijbehorende campagnemetadata in binnen externe systemen.
pass_template_updatedTEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATEDVervers gecachete sjabloonveldkoppelingen of bundleId-instellingen.
app_scan_createdAPP_SCAN_CREATED, LOCATION_ENTEREDLeg winkelbezoek, loyaliteitstoekenning, geofence-binnenkomst of ticket-check-in vast in BI.
message_sentMESSAGE_SENT, NOTIFICATION_SENTLog aflevering van toegangsscherm-push of campagnebericht in klantgeschiedenis.
message_failedMESSAGE_FAILEDWaarschuw operaties of activeer terugvalkanaal via sms of e-mail.

Uitgaande Push HTTP-headers

Elke uitgaande POST-aanvraag van Push Webhook Dispatcher bevat:

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

HMAC-SHA256-handtekeningverificatie (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);
}

SSRF-bescherming, herpogingen & circuit breaker

  • SSRF-doelvalidatie (Webhook URL Validator): Weigert registratie en aflevering naar loopback (127.0.0.0/8, ::1), RFC 1918-privénetwerken (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local en cloud-metadata-IP's (169.254.169.254).
  • Exponentiële Backoff: Antwoorden anders dan 2xx of time-outs van 10s (DEFAULT_TIMEOUT_MS) worden tot 5 keer (DEFAULT_MAX_RETRIES) opnieuw geprobeerd met jitter en exponentiële wachttijd.
  • Circuit Breaker: Na 10 opeenvolgende mislukte leveringen (CIRCUIT_BREAKER_THRESHOLD) opent circuitOpenedAt het circuit voor een afkoelperiode van 30 minuten (CIRCUIT_BREAKER_COOLDOWN_MS) alvorens opnieuw te testen.

2. Pull Webhooks (Webhook Pull API)

Wanneer uw server achter een bedrijfsfirewall of NAT draait zonder inkomende openbare HTTPS-toegang, configureert u een Pull Webhook en pollt u gebeurtenissen via uitgaand HTTPS op GET /webhook-payload (of alias GET /api/v3/webhook-payload):

Wachtrijpayloads ophalen (GET /webhook-payload)

GET /webhook-payload?webhookId=whk_01hxyz5512&limit=100&since=2026-11-16T08:00:00.000Z Header: x-api-key: pi_live_... (standaard 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
}

Verwerkte gebeurtenissen bevestigen (POST /webhook-payload/acknowledge)

Zodra uw worker de batch heeft opgeslagen, bevestigt u tot en met het laatst verwerkte payload-ID (POST /webhook-payload/acknowledge of POST /api/v3/webhook-payload/acknowledge) om deze uit de wachtrij te verwijderen:

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

Raadpleeg Testen & foutopsporing en de Webhooks API-referentie voor payloadschema's.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.