Skip to content
Help Center Guide · Developer API
4 min readVerified 2026-11-16

Webhooks & Events

Subscribe to real-time lifecycle callbacks (pass added, removed, scanned, updated) and verify HMAC-SHA256 webhook signatures.

In This Guide

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. 1
    Push Webhooks (Push Webhook Dispatcher): Real-time outgoing HTTPS POST callbacks 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 = 10 consecutive failures, 30-minute cooldown).
  2. 2
    Pull Webhooks (Webhook Pull API): A prefix-free inbound queue-polling API (GET /webhook-payload / GET /api/v3/webhook-payload and POST /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-Signature header against the raw, unparsed HTTP request body bytes using crypto.timingSafeEqual before 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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
DUAL-MODE PUSH & PULL WEBHOOK DELIVERY
STAGE 01 Passinstance Event Bus
STAGE 02 Mode 1: Push Webhook Delivery (Push Webhook Dispatcher)
1
Validate Target URL (Webhook URL Validator: block private/SSRF IPs)
2
Sign Payload (Webhook Signing EngineX-Webhook-Signature: sha256=<hmac>)
3
POST to Customer HTTPS Endpoint (User-Agent: Passinstance-Webhook/2.0)
4
On 5xx / Timeout (10s default): Retry up to 5x with jittered exponential backoff +-- 5. On 10 consecutive failures: Trip Circuit Breaker (30-minute cooldown)
STAGE 03 Mode 2: Pull Webhook Queue (Webhook Pull API)
-- 1. Enqueue event payload into tenant pull buffer -- 2. Firewall-restricted client polls: GET/webhook-payload?webhookId=...&limit=100&since=... +-- 3. Client commits processed cursor: POST/webhook-payload/acknowledge { upTo: "wpl_01hxyz...", webhookId }

Subscription Management Endpoints (Webhooks API)

MethodEndpointPurpose
GET/api/v1/webhooksRetrieves workspace webhook overview and delivery statistics.
GET / POST/api/v1/webhooks/subscriptionsLists or creates outgoing webhook subscriptions (events, HTTPS url, optional filters).
PATCH/api/v1/webhooks/subscriptions/:idUpdates subscribed events, active status, or target endpoint URL.
DELETE/api/v1/webhooks/subscriptions/:idDeletes a webhook subscription.
POST/api/v1/webhooks/subscriptions/:id/regenerate-secretRotates the HMAC-SHA256 signing secret for a subscription.
POST/api/v1/webhooks/subscriptions/:id/testSends a diagnostic probe delivery and resets circuit breaker state.
GET/api/v1/webhooks/eventsReturns canonical WebhookEventType metadata and sample payloads.
GET/api/v1/webhooks/historyInspects 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 WebhookEventTypeMapped webhook event ValuesPrimary Use Case
pass_createdPASS_CREATED, USER_REGISTERED, PAYMENT_SUCCESS, TICKET_PURCHASEDSync passId, externalId, and smart link back to CRM contact record.
pass_updatedPASS_UPDATED, USER_LOGIN, PAYMENT_PROCESSED, AUDIT_LOG_CREATED, AUDITLOGMirror updated loyalty tier, externalId, or prepaid balance in external ERP.
pass_voidedPASS_VOIDED, PASS_REVOKED, PASS_DELETEDMark voucher code as spent or revoked in e-commerce checkout database.
first_pushnotification_registeredPUSHNOTIFICATION_FIRST, DEVICE_FIRST_REGISTERED, PASS_FIRST_DOWNLOADTrigger welcome bonus workflow when installed for the first time.
pushnotification_registeredPUSHNOTIFICATION_REGISTERED, DEVICE_REGISTERED, PASS_DOWNLOADEDTrack multi-device adoption (e.g., iPhone + paired Apple Watch).
pushnotification_unregisteredPUSHNOTIFICATION_UNREGISTERED, DEVICE_UNREGISTERED, PASS_REMOVEDUpdate CRM uninstall/opt-out status or trigger win-back sequence.
pass_template_createdTEMPLATE_CREATEDProvision corresponding campaign metadata in external systems.
pass_template_updatedTEMPLATE_UPDATED, TEMPLATE_PUBLISHED, TEMPLATE_DELETED, CUSTOMER_REGIONAL_SETTINGS_UPDATEDRefresh cached template field mappings or bundleId settings.
app_scan_createdAPP_SCAN_CREATED, LOCATION_ENTEREDRecord store visit, loyalty accrual, geofence entry, or ticket check-in in BI.
message_sentMESSAGE_SENT, NOTIFICATION_SENTLog lock-screen push or campaign delivery touchpoint in customer timeline.
message_failedMESSAGE_FAILEDAlert operations or trigger fallback SMS/email channel.

Outgoing Push HTTP Headers

Every outgoing POST request from Push Webhook Dispatcher includes:

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 Signature Verification (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 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-2xx responses or 10s (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), circuitOpenedAt opens 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)

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
}

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:

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

See Testing & Debugging and the Webhooks API Reference for payload schemas.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.