REST API Reference & SDKs

Passinstance Developer Documentation

Build high-volume Apple Wallet (.pkpass) and Google Wallet integrations. Issue, update, scan, and broadcast real-time lockscreen notifications via production-grade REST APIs.

Get API Keys

Developer Docs/Webhooks

REST API v1

All API Reference Passes Templates Scanner & Devices Push & Delivery Webhooks Batch Operations

Webhooks

Webhook HMAC Signature Verification

Passinstance signs all outbound webhook deliveries using HMAC-SHA256. Verify the X-Passinstance-Signature header using your subscription secret to prevent spoofing and replay attacks.

Signature Header

X-Passinstance-Signature: t=1755811200,v1=9f8e7d6c5b4a3...

Replay Window

Reject webhook deliveries with timestamps older than 5 minutes (300s)

Supported Events

PASS_CREATED, PASS_UPDATED, PASS_SCANNED, PASS_INSTALLED, PASS_UNINSTALLED

Expected Response

Return HTTP 200 OK within 5,000ms to acknowledge receipt

POSThttps://api.passinstance.com/api/v1/webhooks/subscriptions

Bearer

Create webhook subscription

Register an HTTPS endpoint to receive HMAC-signed real-time event notifications for pass issuance, updates, scans, and uninstalls.

CreateWebhookSubscriptionDto containing target HTTPS destination URL and array of WebhookEventEnum items.

Request Body2 required • 1 optional

urlstring (HTTPS URL)

Required

Your server endpoint URL (must start with https://, max 2048 chars).

example: https://your-server.com/webhooks/passinstance

eventsstring[] (enum)

Required

PASS_CREATED, PASS_UPDATED, PASS_DELETED, PASS_SCANNED, PASS_REDEEMED, PASS_INSTALLED, PASS_UNINSTALLED.

example: ["PASS_CREATED", "PASS_UPDATED", "PASS_SCANNED"]

Response Status Codes

201Created

ApiResponseDto with webhook registration and HMAC signature secret.

Related:List webhook subscriptions

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptions

Bearer

List webhook subscriptions

Retrieve all active webhook subscriptions registered for your customer workspace.

Response Status Codes

200OK

ApiResponseDto<WebhookSubscription[]> array with active subscription endpoints.

Related:Create webhook subscription

POST/webhooks/subscriptions

Webhooks

Request

curl -X POST https://api.passinstance.com/api/v1/webhooks/subscriptions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/passinstance",
    "events": ["PASS_CREATED", "PASS_UPDATED", "PASS_SCANNED"]
  }'

Response

CreatedApiResponseDto with webhook registration and HMAC signature secret.

{
  "success": true,
  "data": {
    "id": "wh_sub_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "url": "https://your-server.com/webhooks/passinstance",
    "events": [
      "PASS_CREATED",
      "PASS_UPDATED",
      "PASS_SCANNED"
    ],
    "secret": "whsec_98f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9",
    "status": "ACTIVE",
    "createdAt": "2026-08-21T20:30:00.000Z"
  },
  "description": "Webhook subscription registered successfully",
  "errors": [],
  "statusCode": 201
}

Envelope: ApiResponseDto<T>HTTPS (TLS 1.3)