Webhook Events
Event types and payload structures
Envelope
All webhook events are delivered as HTTP POST requests with a JSON body. The envelope contains metadata about the event plus an event-specific data payload.
{
"id": "9f8c2a1b7e4d6c0a3f5b8e2d1c4a7b9e",
"event": "tag.moved",
"occurredAt": "2024-06-19T13:45:23Z",
"test": false,
"tag": {
"id": "aB3xK9Qm1Zr7",
"name": "My AirTag",
"originalPhysicalLabel": "01",
"hardwareId": "00000000AABBCCDD",
"labels": ["Coca-Cola", "Seattle"]
},
"data": { ... event-specific ... }
}id: Unique delivery ID (for deduplication). The delivery id is an opaque hex token.
event: Event type (e.g., "tag.moved").
occurredAt: ISO 8601 timestamp for when TagLogger detected and emitted the event (detection time, which can lag the underlying change). For the physical signal, read data.lastSeenAt (offline) or data.to (moved).
test: Boolean. True if this is a test delivery (sent via the test button), false for live events.
tag: Tag reference (id, name, originalPhysicalLabel, hardwareId, labels). tag.name may be null if the tag has no custom name; tag.originalPhysicalLabel may be null when no original shipped or provisioned label was recorded.
data: Event-specific fields (varies by event type).
Event Types
tag.moved
Sent when a tag's location is updated. To suppress noise from minor location jitter, this fires only once a tag has moved at least 150 meters from the position reported in its previous tag.moved event.
{
"id": "9f8c2a1b7e4d6c0a3f5b8e2d1c4a7b9e",
"event": "tag.moved",
"occurredAt": "2024-06-19T13:45:23Z",
"test": false,
"tag": { "id": "aB3xK9Qm1Zr7", "name": "My Tag", "originalPhysicalLabel": "01", "hardwareId": "...", "labels": ["Coca-Cola"] },
"data": {
"from": { "lat": 40.7128, "lng": -74.0060 },
"to": { "lat": 40.7580, "lng": -73.9855 },
"distanceMeters": 5200
}
}from: Previous coordinates (lat, lng).
to: New coordinates (lat, lng).
distanceMeters: Straight-line distance between the from and to coordinates (not cumulative path length).
tag.battery_low
Sent when a tag's battery reports Low, an early warning to plan a swap, and again if it reaches Critical, when the battery should be replaced soon. A Good or Medium report re-arms the event.
{
"id": "9f8c2a1b7e4d6c0a3f5b8e2d1c4a7b9e",
"event": "tag.battery_low",
"occurredAt": "2024-06-19T13:45:23Z",
"test": false,
"tag": { "id": "aB3xK9Qm1Zr7", "name": "My Tag", "originalPhysicalLabel": "01", "hardwareId": "...", "labels": ["Coca-Cola"] },
"data": {
"status": 3,
"critical": false
}
}status: An integer on the battery scale (3 = low, 4 = critical). Use the boolean critical field for a simple check.
critical: Boolean. True at Critical: replace the battery soon, the tag may stop reporting.
tag.offline
Sent when a tag stops reporting its location for an extended period (roughly six hours of silence). This usually means the tag's battery has died, or the tag is somewhere it cannot currently be located.
{
"id": "9f8c2a1b7e4d6c0a3f5b8e2d1c4a7b9e",
"event": "tag.offline",
"occurredAt": "2024-06-19T13:45:23Z",
"test": false,
"tag": { "id": "aB3xK9Qm1Zr7", "name": "My Tag", "originalPhysicalLabel": "01", "hardwareId": "...", "labels": ["Coca-Cola"] },
"data": {
"lastSeenAt": "2024-06-19T07:30:00Z",
"staleSeconds": 22523
}
}lastSeenAt: ISO 8601 timestamp of the last location report.
staleSeconds: Seconds elapsed since the last location was seen.
When Events Are Not Emitted
While a tag's recording is paused (recordingPaused: true), no tag.* events are emitted for that tag — location updates, battery checks, and offline detection are all suspended until recording resumes. See Recording Pause for details.
Geofence Events
Geofence events fire when a monitored tag crosses one of your geofence boundaries. They use the same envelope as tag events, with the geofence and the crossing location carried in data:
- geofence.entry — A tag moved from outside to inside a geofence (a check-in). For a corridor this means the tag is back on the route.
- geofence.exit — A tag moved from inside to outside a geofence (a check-out). For a corridor this is a route deviation: the tag left the route.
- geofence.dwell — A tag has stayed outside a geofence past its configured dwell threshold (a "still outside" reminder; for a corridor, "still off the route").
{
"id": "1c4a7b9e0d6c3f5b8e2d9f8c2a1b7e4d",
"event": "geofence.entry",
"occurredAt": "2024-06-19T13:45:23Z",
"test": false,
"tag": {
"id": "aB3xK9Qm1Zr7",
"name": "My AirTag",
"originalPhysicalLabel": "01",
"hardwareId": "00000000AABBCCDD",
"labels": ["Coca-Cola", "Seattle"]
},
"data": {
"geofence": {
"id": "Gf12Xy34Zq56",
"name": "Warehouse",
"type": "circle",
"center": { "lat": 37.7751, "lng": -122.4190 },
"radiusMeters": 150
},
"location": { "lat": 37.7749, "lng": -122.4194 }
}
}data.geofence: The geofence's id, name and shape, in the same form as the Geofence object: type is circle, polygon or corridor. A circle has center and radiusMeters; a polygon adds vertices; a corridor adds path and widthMeters, and for both radiusMeters is null. The shape fields are left out when the geofence was deleted or changed to another shape type after the event.
data.location: The tag position at the crossing, or null if unavailable.
data.dwellMinutes: Present only on geofence.dwell — the configured dwell threshold in minutes.
data.visitDurationMs: Present only on geofence.exit when the matching entry is known — how long the tag was inside, in milliseconds.
Geofence email alerts configured in the geofence's own settings continue to fire independently of webhook delivery.
Security Events
security.event delivers each company sign-in security event as it is recorded: connection, domain, certificate, SCIM token and setup-link changes, members provisioned or removed, denied sign-ins, and policy changes. Its envelope has no tag; data is the event exactly as GET /v1/security-events returns it:
{
"id": "4e7b1c9a-2d5f-4e3b-9a0c-1d4f7e2a5b8c",
"event": "security.event",
"occurredAt": "2024-06-19T13:45:23Z",
"test": false,
"data": {
"id": "4e7b1c9a-2d5f-4e3b-9a0c-1d4f7e2a5b8c",
"type": "domain.verified",
"occurredAt": "2024-06-19T13:45:23Z",
"connectionId": "Cn12Ab34Cd56",
"actor": { "kind": "system" },
"details": { "domain": "acme.example" }
}
}id: The security event's id, equal to data.id and safe to use as an idempotency key.
data.type: What happened; the set may grow, so handle unknown values gracefully.
data.actor: Who or what caused it (kind is owner, admin, member, setupLink, scim, system or staff); only the fields that apply are present.
data.details: Event-specific detail, for example the member, domain or reason.
A subscription receives security events only when it names security.event and its API key has the read:security-events scope: leaving events out subscribes to every type except this one. Security events are delivered as soon as a subscription names them; no TagLogger action is needed. A test delivery always sends a sample tag.moved event.
Delivery Activation
Webhook delivery for tag.* and geofence.* events is independently operator-gated and off by default at launch. A subscription you create begins receiving deliveries automatically once delivery is enabled for production — no changes are needed on your side, and existing subscriptions activate on their own. Subscribe to the event types you want now; you do not have to wait for activation to build and test your integration (use the test endpoint to exercise your handler end to end).