Webhook API
Developer Docs

Webhook API

Receive real-time notifications when events happen in your account. Verify with HMAC-SHA256 signatures.

POSTHMAC-SHA256Auto retry5s timeout

Method

POST

JSON payload

Signature

HMAC

SHA-256

Timeout

5s

Per request

Retries

3×

Exponential backoff

Overview

How webhooks work

When an event you're subscribed to fires, we send an HTTP POST request to your configured URL with a JSON payload and a signature header so you can verify the request came from us.

1Configure

Add your URL and pick which events to subscribe to

2Receive

We POST a signed JSON payload when events fire

3Verify & handle

Check the signature, then process asynchronously

Payload

Every event has this shape

json
{
  "event": "user.checkin",
  "timestamp": "2026-01-15T10:30:45.123Z",
  "data": {
    "userId": "507f1f77bcf86cd799439011",
    "userName": "John Doe",
    "deviceId": "507f1f77bcf86cd799439012",
    "deviceName": "Main Gate",
    "rfidTagId": "ABC123DEF",
    "status": "ON_TIME",
    "checkInTime": "2026-01-15T10:30:45.000Z"
  },
  "apiKeyId": "507f1f77bcf86cd799439013",
  "tenantId": "507f1f77bcf86cd799439014",
  "webhookId": "507f1f77bcf86cd799439013"
}
Field reference
FieldTypeDescription
eventstringEvent name (see list below)
timestampISO 8601When the event was fired
dataobjectEvent-specific payload
apiKeyIdstringOwning API key ID
tenantIdstringYour tenant / organization ID
webhookIdstringUnique webhook identifier

Headers

Sent with every request

Content-TypeAlways application/json
X-Webhook-SignatureHMAC-SHA256 signature of the payload
X-Webhook-EventEvent name (e.g. user.checkin)
X-Webhook-TimestampISO 8601 timestamp of when sent
X-Webhook-TestPresent and "true" only for test events
(custom headers)Any headers you configured on the webhook

Available events

Subscribe to these event names

user.checkin

User checked in

user.checkout

User checked out

user.late

User arrived late

user.early_leave

User left early

gatepass.created

Gate pass created

gatepass.used

Gate pass used

device.offline

Device went offline

device.online

Device came online

user.created

New user registered

user.deleted

User removed

rfidcard.requested

RFID cards requested

rfidcard.approved

RFID request approved

devicerequest.requested

Device requested

devicerequest.approved

Device request approved

webhook.test

Test event

Verifying signatures

Always verify before trusting

Every request includes an X-Webhook-Signature header — an HMAC-SHA256 of the raw request body using your webhook secret. Use a constant-time comparison to prevent timing attacks.

Node.js
javascript
const crypto = require('crypto');
const express = require('express');

app.post(
  '/webhooks/rfid',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-webhook-signature'];
    const expected = crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

    const valid =
      signature &&
      signature.length === expected.length &&
      crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
      );

    if (!valid) return res.status(401).end();

    res.status(200).json({ received: true });
    handleEvent(JSON.parse(req.body.toString()));
  }
);
Python
python
import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = b'your_webhook_secret'

@app.route('/webhooks/rfid', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    raw_body = request.get_data()

    expected = hmac.new(
        WEBHOOK_SECRET,
        raw_body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature or '', expected):
        abort(401)

    payload = request.get_json()
    # process...
    return '', 200

Use express.raw() — not express.json() — on your webhook route. JSON parsing modifies the body and will break signature verification.

Retry policy

What happens on failure

If your endpoint returns a non-2xx status, times out, or refuses the connection, we retry with exponential backoff:

1st retry

1s

2nd retry

2s

3rd retry

4s

Retries use the same signature and payload as the original. For idempotency, dedupe on X-Webhook-Timestamp or a unique field inside data.

Testing

Verify your endpoint works

From the dashboard, click Test Webhook in your API key settings. This sends a webhook.test event to your URL:

json
{
  "event": "webhook.test",
  "timestamp": "2026-01-15T10:30:45.123Z",
  "data": {
    "message": "This is a test webhook notification",
    "test": true
  },
  "apiKeyId": "...",
  "tenantId": "...",
  "webhookId": "..."
}
Or use curl
bash
curl -X POST https://your-app.com/webhooks/rfid \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Test: true" \
  -H "X-Webhook-Event: webhook.test" \
  -d '{"event":"webhook.test","data":{"test":true}}'

Best practices

Do's and don'ts

Do
  • Verify every signature
  • Respond within 5 seconds
  • Always use HTTPS
  • Store secrets in env vars
  • Handle duplicate deliveries
  • Log raw payloads for debugging
Don't
  • Process synchronously for > 5s
  • Expose the secret client-side
  • Return HTML from the endpoint
  • Call back into our API
  • Trust unsigned payloads
  • Assume exactly-once delivery

Full example

Express + Bull queue

javascript
const crypto = require('crypto');
const express = require('express');
const Queue = require('bull');

const app = express();
const eventQueue = new Queue('webhooks');

app.post(
  '/webhooks/rfid',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // 1. Verify signature
    const signature = req.headers['x-webhook-signature'];
    const expected = crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

    if (
      !signature ||
      !crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
      )
    ) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // 2. Parse
    const payload = JSON.parse(req.body.toString());

    // 3. Ack immediately
    res.status(200).json({ received: true });

    // 4. Queue for async processing
    await eventQueue.add(payload.event, payload, {
      jobId: `${payload.event}-${payload.timestamp}`,
      attempts: 3,
      backoff: { type: 'exponential', delay: 2000 },
    });
  }
);

// Worker
eventQueue.process('*', async (job) => {
  const { event, data } = job.data;

  switch (event) {
    case 'user.checkin':
      await db.checkIns.insert(data);
      break;
    case 'user.checkout':
      await db.checkOuts.insert(data);
      break;
    case 'device.offline':
      await alerts.sendOfflineAlert(data);
      break;
  }
});

app.listen(3000);

Troubleshooting

Common issues

Webhooks aren't arriving

Check the URL is publicly reachable, your server accepts POST, firewall/proxy allows us through, and the webhook is active.

Signature verification fails

Make sure you're using the raw request body (not re-stringified JSON). Verify the secret matches exactly with no whitespace.

Duplicate events

Retries can deliver the same event more than once. Use X-Webhook-Timestamp or a data field as an idempotency key.

Timeouts

If your handler takes > 5 seconds, we'll mark it as failed and retry. Always ack first, process later.

Need help integrating?

Reach out with your tenant ID, webhook URL, and the failing event name.

Contact Support