Webhook Delivery and Signature Verification
How webhooks are delivered and how to verify signatures
Delivery Characteristics
Webhook deliveries are at-least-once:
- Automatic retries: When an event occurs, TagLogger POSTs it to your endpoint. If that attempt fails (a non-2xx response or a timeout), it is retried automatically with exponential backoff over several attempts before being marked permanently failed.
- May deliver more than once: Because of retries—and occasional overlap—the same event can arrive more than once. Make your handler idempotent by de-duplicating on the envelope's
id(see Idempotency below). - No ordering guarantee: Events may arrive out of order. Always use the
occurredAttimestamp to determine sequence. - Notifications, not history: Webhooks are a fast notification channel, not a complete transaction log. Treat them as a signal to poll the API for the authoritative state.
You can inspect the status and attempt count of recent deliveries for any subscription with GET /v1/webhooks/{webhookId}/deliveries.
Going Live
Tag event webhooks (tag.moved, tag.battery_low, tag.offline) are off by default at launch. You can create subscriptions immediately, and they begin receiving live deliveries automatically once production delivery is enabled—there is no per-workspace switch to request and no change needed on your side.
In the meantime, POST /v1/webhooks/{webhookId}/test deliveries are sent right away regardless of the launch state, so you can build and verify your endpoint—signature checks included—before live events begin.
HTTP Format
Webhooks are delivered as HTTP POST requests with the following characteristics:
Content-Type: application/json
Body: JSON event envelope (see Events page for schema)
Signature: X-TagLogger-Signature header (see below)
Timeout: Your endpoint should respond within 10 seconds (we recommend keeping your handler under 5 seconds for headroom)
Signature Verification
Every webhook delivery includes a signature in the X-TagLogger-Signature header. Always verify the signature before processing the event. This ensures the POST came from TagLogger and wasn't forged.
How to Verify
- Extract the
X-TagLogger-Signatureheader from the request. - Compute HMAC-SHA256 of the raw JSON body using your webhook's signing secret as the key.
- Strip the
sha256=prefix from the header value, then compare it against your computed hash (hex-encoded) using a constant-time comparison. - If they match, the event is authentic. If they don't match, reject the request and log a security alert.
Example (Node.js)
const crypto = require('crypto');
function verifySignature(body, signatureHeader, secret) {
// The header arrives as "sha256=<hex>" — compare against just the hex.
const provided = (signatureHeader || '').replace(/^sha256=/, '');
const expected = crypto
.createHmac('sha256', secret)
.update(body, 'utf8')
.digest('hex');
// timingSafeEqual throws on a length mismatch, so guard the length first.
return (
provided.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(provided), Buffer.from(expected))
);
}
// In your webhook handler:
app.post('/webhooks', (req, res) => {
const sig = req.headers['x-taglogger-signature'];
const body = req.rawBody; // Must be raw, not parsed JSON
if (!verifySignature(body, sig, process.env.WEBHOOK_SECRET)) {
return res.status(401).json({ error: 'Signature mismatch' });
}
// Safe to process the event
const event = JSON.parse(body);
res.sendStatus(200);
});Signature Format
The signature header has the format sha256=<hex>, where <hex> is the hexadecimal-encoded HMAC-SHA256 hash.
Handling Missed Deliveries
Retries make delivery resilient to transient endpoint failures, but a webhook subscription that is down for an extended window (longer than the retry budget) can still exhaust its attempts and be marked permanently failed. Webhooks remain a low-latency notification, not a ledger, so poll the API to reconcile authoritative state and backfill anything you missed. Use GET /v1/fleet/delta as your source of truth.
// Poll the fleet delta every few minutes to catch any missed webhooks
async function syncTags() {
const response = await fetch(
'https://api.taglogger.com/v1/fleet/delta?since=2024-06-19T12:00:00Z',
{ headers: { 'Authorization': 'Bearer tl_live_xxx' } }
);
const { data, nextCursor } = await response.json();
for (const change of data) {
// Process each changed tag
console.log(`Tag ${change.tagId} last seen ${change.lastSeenAt}`, change.location);
}
// Use nextCursor for pagination if needed
}Idempotency
Each delivery carries a unique id field in the event envelope. Because deliveries are at-least-once, the same event id can legitimately arrive more than once—a retry after a slow 200, or overlap at a delivery boundary. Record processed IDs and skip duplicates so reprocessing the same event is harmless.
Store the delivered event ID in your database alongside your processing result. If you see the same ID again, skip processing and respond with 200.
Best Practices
- Verify signatures: Always check X-TagLogger-Signature before trusting the payload.
- Respond quickly: Acknowledge receipt immediately with a 2xx response (for example, 200 OK). Do heavy processing asynchronously in a background job.
- Use HTTPS: Your webhook endpoint must be served over HTTPS.
- Poll the fleet delta: Don't rely on webhooks alone. Poll GET /v1/fleet/delta on an interval to reconcile the authoritative state.
- Be idempotent: Deliveries are at-least-once, so de-duplicate on the envelope
idand make reprocessing the same event harmless. - Return 2xx only when you've accepted the event: A non-2xx response (or a timeout) signals failure and triggers an automatic retry with exponential backoff. Respond 2xx as soon as you've durably accepted the event, then process asynchronously.
- Log deliveries: Store the event ID, timestamp, and processing result for debugging and auditing. You can also inspect server-side delivery status and attempt counts via GET /v1/webhooks/{webhookId}/deliveries.
- Handle ordering: Events may arrive out of order. Use occurredAt timestamps to determine the actual sequence.