Overview
Passinstance provides a dual-mode webhook architecture managed via /api/v1/webhooks/subscriptions (or in Workspace Settings -> Developer -> Webhooks at /settings/workspace/developer/webhooks) so you can synchronize wallet lifecycle events with any infrastructure:
-
1
Push Webhooks (
Push Webhook Dispatcher): Real-time outgoing HTTPSPOSTcallbacks signed with per-subscription HMAC-SHA256 secrets (X-Webhook-Signature), protected by SSRF target validation, automatic jittered exponential backoff retries (DEFAULT_MAX_RETRIES = 5), and a per-endpoint circuit breaker (CIRCUIT_BREAKER_THRESHOLD = 10consecutive failures,30-minute cooldown). -
2
Pull Webhooks (
Webhook Pull API): A prefix-free inbound queue-polling API (GET /webhook-payload/GET /api/v3/webhook-payloadandPOST /webhook-payload/acknowledge/POST /api/v3/webhook-payload/acknowledge) designed for firewall-restricted, on-premise, or local ERP servers that cannot expose public inbound HTTPS ports.
Important: Always verify the
X-Webhook-Signatureheader against the raw, unparsed HTTP request body bytes usingcrypto.timingSafeEqualbefore parsing JSON or executing business logic. Re-serializing a parsed JSON object changes whitespace or key ordering and invalidates the HMAC digest.
Dual-Mode Webhook Architecture
Subscription Management Endpoints (Webhooks API)
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/webhooks | Retrieves workspace webhook overview and delivery statistics. |
GET / POST | /api/v1/webhooks/subscriptions | Lists or creates outgoing webhook subscriptions (events, HTTPS url, optional filters). |
| PATCH | /api/v1/webhooks/subscriptions/:id | Updates subscribed events, active status, or target endpoint URL. |
| DELETE | /api/v1/webhooks/subscriptions/:id | Deletes a webhook subscription. |
| POST | /api/v1/webhooks/subscriptions/:id/regenerate-secret | Rotates the HMAC-SHA256 signing secret for a subscription. |
| POST | /api/v1/webhooks/subscriptions/:id/test | Sends a diagnostic probe delivery and resets circuit breaker state. |
| GET | /api/v1/webhooks/events | Returns canonical WebhookEventType metadata and sample payloads. |
| GET | /api/v1/webhooks/history | Inspects historical deliveries and attempt logs (/api/v1/webhooks/history/:eventHistoryId/attempts). |
1. Canonical Event Types & Passinstance database webhook event Mapping
WebhookEventRegistry normalizes 31 internal Passinstance database webhook event domain values into 11 canonical WebhookEventType strings emitted to webhook receivers (legacy dot notation aliases like pass.created are also mapped cleanly at subscription creation time):
Canonical WebhookEventType | Mapped webhook event Values | Primary Use Case |
|---|---|---|
pass_created | PASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASED | Sync passId, externalId, and smart link back to CRM contact record. |
pass_updated | PASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOG | Mirror updated loyalty tier, externalId, or prepaid balance in external ERP. |
pass_voided | PASS_VOIDED, PASS_REVOKED, PASS_DELETED | Mark voucher code as spent or revoked in e-commerce checkout database. |
first_pushnotification_registered | PUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOAD | Trigger welcome bonus workflow when installed for the first time. |
pushnotification_registered | PUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADED | Track multi-device adoption (e.g., iPhone + paired Apple Watch). |
pushnotification_unregistered | PUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVED | Update CRM uninstall/opt-out status or trigger win-back sequence. |
pass_template_created | TEMPLATE_CREATED | Provision corresponding campaign metadata in external systems. |
pass_template_updated | TEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATED | Refresh cached template field mappings or bundleId settings. |
app_scan_created | APP_SCAN_CREATED, LOCATION_ENTERED | Record store visit, loyalty accrual, geofence entry, or ticket check-in in BI. |
message_sent | MESSAGE_SENT, NOTIFICATION_SENT | Log lock-screen push or campaign delivery touchpoint in customer timeline. |
message_failed | MESSAGE_FAILED | Alert operations or trigger fallback SMS/email channel. |
Outgoing Push HTTP Headers
Every outgoing POST request from Push Webhook Dispatcher includes:
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 Signature Verification (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 Protection, Retries & Circuit Breaker
-
SSRF Target Validation (
Webhook URL Validator): Rejects registration and delivery to loopback (127.0.0.0/8,::1), RFC 1918 private networks (10.0.0.0/8,172.16.0.0/12,192.168.0.0/16), link-local, and cloud metadata IPs (169.254.169.254). -
Exponential Backoff: Non-
2xxresponses or10s(DEFAULT_TIMEOUT_MS) timeouts are retried up to 5 times (DEFAULT_MAX_RETRIES) with jittered exponential backoff. -
Circuit Breaker: After 10 consecutive delivery failures (
CIRCUIT_BREAKER_THRESHOLD),circuitOpenedAtopens the breaker for a 30-minute cooldown period (CIRCUIT_BREAKER_COOLDOWN_MS) before probing again.
2. Pull Webhooks (Webhook Pull API)
When your server runs behind a corporate firewall or NAT without inbound public HTTPS access, configure a Pull Webhook and poll queued events over outbound HTTPS using GET /webhook-payload (or alias GET /api/v3/webhook-payload):
Poll Queued Payloads (GET /webhook-payload)
GET /webhook-payload?webhookId=whk_01hxyz5512&limit=100&since=2026-11-16T08:00:00.000Z Header: x-api-key: pi_live_... (default 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
}
Acknowledge Processed Events (POST /webhook-payload/acknowledge)
Once your worker persists the batch, acknowledge up to the last processed payload ID (POST /webhook-payload/acknowledge or POST /api/v3/webhook-payload/acknowledge) so those events are dequeued:
{
"webhookId": "whk_01hxyz5512",
"upTo": "wpl_01hxyz8801"
}
See Testing & Debugging and the Webhooks API Reference for payload schemas.
