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
Push Webhooks (
Push Webhook Dispatcher): Realtime uitgaande HTTPSPOST-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 = 10opeenvolgende fouten,30minuten afkoelperiode). -
2
Pull Webhooks (
Webhook Pull API): Een prefixvrije inkomende polling-wachtrij-API (GET /webhook-payload/GET /api/v3/webhook-payloadenPOST /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-Signaturealtijd tegen de ruwe, ongeparste HTTP-requestbodybytes metcrypto.timingSafeEqualvoordat 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
Endpoints voor abonnementsbeheer (Webhooks API)
| Methode | Endpoint | Doel |
|---|---|---|
| GET | /api/v1/webhooks | Haalt werkruimte-webhookoverzicht en afleverstatistieken op. |
GET / POST | /api/v1/webhooks/subscriptions | Toont of maakt uitgaande webhook-abonnementen (events, HTTPS url, optionele filters). |
| PATCH | /api/v1/webhooks/subscriptions/:id | Werkt geabonneerde gebeurtenissen, actieve status of doel-URL bij. |
| DELETE | /api/v1/webhooks/subscriptions/:id | Verwijdert een webhook-abonnement. |
| POST | /api/v1/webhooks/subscriptions/:id/regenerate-secret | Roteert het HMAC-SHA256-ondertekeningsgeheim van een abonnement. |
| POST | /api/v1/webhooks/subscriptions/:id/test | Verzendt een diagnostische testaanvraag en reset de circuit-breakerstatus. |
| GET | /api/v1/webhooks/events | Retourneert canonieke WebhookEventType-metadata en voorbeeldpayloads. |
| GET | /api/v1/webhooks/history | Inspecteert 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 WebhookEventType | Gekoppelde webhook event-waarden | Belangrijkste toepassing |
|---|---|---|
pass_created | PASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASED | Synchroniseer passId, externalId en slimme link terug naar CRM-contactrecord. |
pass_updated | PASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOG | Spiegel bijgewerkt loyaliteitsniveau, externalId of prepaidtegoed in extern ERP. |
pass_voided | PASS_VOIDED, PASS_REVOKED, PASS_DELETED | Markeer waardeboncode als gebruikt of ingetrokken in e-commerce checkout-database. |
first_pushnotification_registered | PUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOAD | Start welkomstbonus-workflow bij eerste Wallet-installatie. |
pushnotification_registered | PUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADED | Volg adoptie op meerdere apparaten (bijv. iPhone + gekoppelde Apple Watch). |
pushnotification_unregistered | PUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVED | Werk CRM-verwijder-/opt-outstatus bij of start een terugwinactie. |
pass_template_created | TEMPLATE_CREATED | Richt bijbehorende campagnemetadata in binnen externe systemen. |
pass_template_updated | TEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATED | Ververs gecachete sjabloonveldkoppelingen of bundleId-instellingen. |
app_scan_created | APP_SCAN_CREATED, LOCATION_ENTERED | Leg winkelbezoek, loyaliteitstoekenning, geofence-binnenkomst of ticket-check-in vast in BI. |
message_sent | MESSAGE_SENT, NOTIFICATION_SENT | Log aflevering van toegangsscherm-push of campagnebericht in klantgeschiedenis. |
message_failed | MESSAGE_FAILED | Waarschuw operaties of activeer terugvalkanaal via sms of e-mail. |
Uitgaande Push HTTP-headers
Elke uitgaande POST-aanvraag van Push Webhook Dispatcher bevat:
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)
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
2xxof time-outs van10s(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) opentcircuitOpenedAthet 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)
{
"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:
{
"webhookId": "whk_01hxyz5512",
"upTo": "wpl_01hxyz8801"
}
Raadpleeg Testen & foutopsporing en de Webhooks API-referentie voor payloadschema's.
