Webhook API
Receive real-time notifications when events happen in your account. Verify with HMAC-SHA256 signatures.
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.
Add your URL and pick which events to subscribe to
We POST a signed JSON payload when events fire
Check the signature, then process asynchronously
Payload
Every event has this shape
{
"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 | Type | Description |
|---|---|---|
| event | string | Event name (see list below) |
| timestamp | ISO 8601 | When the event was fired |
| data | object | Event-specific payload |
| apiKeyId | string | Owning API key ID |
| tenantId | string | Your tenant / organization ID |
| webhookId | string | Unique webhook identifier |
Headers
Sent with every request
Content-TypeAlways application/jsonX-Webhook-SignatureHMAC-SHA256 signature of the payloadX-Webhook-EventEvent name (e.g. user.checkin)X-Webhook-TimestampISO 8601 timestamp of when sentX-Webhook-TestPresent and "true" only for test events(custom headers)Any headers you configured on the webhookAvailable 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.
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()));
}
);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 '', 200Use 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:
{
"event": "webhook.test",
"timestamp": "2026-01-15T10:30:45.123Z",
"data": {
"message": "This is a test webhook notification",
"test": true
},
"apiKeyId": "...",
"tenantId": "...",
"webhookId": "..."
}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
- Verify every signature
- Respond within 5 seconds
- Always use HTTPS
- Store secrets in env vars
- Handle duplicate deliveries
- Log raw payloads for debugging
- 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
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.
Next steps
Continue building
Need help integrating?
Reach out with your tenant ID, webhook URL, and the failing event name.