Webhooks

Webhooks let your application receive real-time events from RemyPass. Create and manage webhook subscriptions from the RemyPass integrations UI.

Supported Events

Event	When it is sent
scan.created	A pass or member scan is recorded

Delivery Payload

Webhook deliveries are sent as POST requests with a JSON body:

{
  "id": "8fd6ce2f-8b55-4b2e-9f8c-5b7f6f0b16f1",
  "event": "scan.created",
  "timestamp": "2024-12-31T23:59:59.000Z",
  "data": {
    "scan": {
      "id": "507f1f77bcf86cd799439015",
      "company": "507f1f77bcf86cd799439010",
      "source": "qr",
      "member": {
        "id": "507f1f77bcf86cd799439011",
        "name": "John Doe",
        "email": "john@example.com",
        "memberId": "MEM001"
      },
      "input": "ABCD1234",
      "location": "Main Entrance",
      "result": "success",
      "reason": "Pass accepted",
      "timestamp": "2024-12-31T23:59:59.000Z"
    }
  }
}

Delivery Headers

Header	Description
Content-Type	Always application/json
User-Agent	RemyPass-Webhooks/1.0
X-RemyPass-Signature	HMAC-SHA256 signature of the raw request body
X-RemyPass-Event	Event name, for example scan.created
X-RemyPass-Delivery	Unique delivery id

Custom headers configured on the webhook subscription are also included with each delivery.

Signature Verification

Use the subscription secret to verify the raw request body before processing the event.

const crypto = require("crypto");

function verifyRemyPassWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

Retries and Timeouts

Your endpoint should return any 2xx status quickly after accepting the event. If the endpoint returns a non-2xx status or times out, RemyPass retries delivery with exponential backoff.

Defaults:

Setting	Default	Limit
Delivery timeout	30 seconds	1 to 300 seconds
Retry delay	60 seconds	1 to 3600 seconds
Max retries	3	0 to 10

Webhook subscriptions are disabled after 10 consecutive delivery failures.

Subscription Management

Webhook subscriptions are managed in the RemyPass UI under Integrations. The public API does not currently support creating, updating, or deleting webhook subscriptions.

When creating a subscription:

• The URL must use HTTPS.
• The URL must be reachable by a HEAD request.
• At least one supported event is required.
• The generated signing secret is returned on creation; later reads return a masked value.