Webhooks Overview
Receive real-time notifications when tag events occur
What are Webhooks?
Webhooks allow you to receive real-time notifications when events occur in your TagLogger workspace. Instead of continuously polling the API for changes, we push events directly to your application.
When you subscribe to an event type (e.g., "tag.moved"), TagLogger sends an HTTP POST to your endpoint whenever that event occurs. Your application processes the event and responds with any 2xx status (for example, 200 OK) to confirm receipt.
Event Types
Seven event types are available across three families—tag, geofence and security events. See the Events page for full payload details.
Tag events
tag.moved
A tag has moved a meaningful distance (at least 150 m) from its last reported position. The payload includes the previous and new coordinates and the straight-line distance between them.
tag.battery_low
A tag's battery reported Low (an early warning to plan a swap) or Critical (replace soon). The payload includes the current battery status and whether it's critical.
tag.offline
A tag stopped reporting location and has not been seen in a while. The payload includes when it was last seen and how long ago.
Geofence events
geofence.entry
A tag moved from outside to inside one of your geofences. The payload includes the geofence and the crossing location.
geofence.exit
A tag moved from inside to outside one of your geofences. The payload includes the geofence and the crossing location.
geofence.dwell
A tag has stayed outside a geofence past its configured dwell threshold (a "still outside" reminder). The payload adds the dwell threshold in minutes.
Security events
security.event
A company sign-in security event was recorded: a connection, domain, certificate, SCIM token or setup-link change, a member provisioned or removed, a denied sign-in, or a policy change. The payload is the event as GET /v1/security-events returns it. It needs the read:security-events scope and is never part of the default set: subscribe to it by name.
Key Concepts
Subscriptions
Webhook subscriptions are managed through the API. Each subscription specifies:
- The endpoint URL where you want to receive events
- Which event types to subscribe to
- An optional label to organize your webhooks
Delivery Guarantees
Webhooks are delivered at-least-once. A failed POST (non-2xx or timeout) is retried automatically with exponential backoff over several attempts before being marked permanently failed. Because of retries the same event may arrive more than once, so de-duplicate on the envelope id. Webhooks remain a low-latency notification rather than a ledger: for anything that must never be missed (a subscription that stays down past the retry budget still gives up), reconcile against the API using GET /v1/fleet/delta as your source of truth. You can review delivery status and attempt counts via GET /v1/webhooks/{webhookId}/deliveries.
Going Live
Webhook delivery is off by default at launch. New subscriptions begin receiving live deliveries automatically once production delivery is enabled—there is no per-workspace request and no change needed on your side. Test deliveries work immediately in the meantime, so you can validate end to end before live events begin.
Getting Started
- Create a subscription with
POST /v1/webhooks, providing your HTTPS endpoint URL and the event types you want to receive - Copy the signing secret from the response (shown only once) and store it securely
- Implement signature verification in your endpoint
- Send a test delivery with
POST /v1/webhooks/{webhookId}/testto validate your endpoint and signature handling - Go live: once production delivery is enabled, your subscription receives live events automatically—no extra step on your side. Until then, use the test endpoint to validate end to end.
See the Webhooks Setup guide for implementation details.