Webhooks tell your backend what happened on the phones: an activity started, got a new token, ended, or Apple refused a push.
Set up
- Open your app in the dashboard, tab Webhooks.
- Enter an
https://URL and save. Leave it empty to turn webhooks off. - Copy the signing secret (
whsec_…) from the same tab. Use Send test event to check that your endpoint answers.
Answer every request with a 2xx within 10 seconds.
The request
We POST JSON:
{
"id": "evt_3q8Zr1mX0aKd7wYp5LbT2g",
"type": "activity.started",
"createdAt": 1795180003000,
"data": { "activity": { … }, "target": { … } }
}
data.activity is the activity object. Headers: Content-Type: application/json and
LAC-Signature.
Events
| Type | When | data |
|---|---|---|
activity.started |
A device reports the activity as active for the first time. | activity, target |
activity.token_updated |
A device reports a new update token for the activity. | activity, target |
activity.ended |
A device reports it ended, or we pushed the end to the devices. | activity, target (device report) or activity only (our end push) |
activity.dismissed |
A device reports that the user dismissed it. | activity, target |
delivery.failed |
The activity couldn’t start, or Apple refused a push. | activity, error, and target for a refused update or end |
token.invalid |
Apple says a token is no longer valid, so we stopped using it. | activity, target, error |
target from a device report is { installId, activityKitId, status }. In delivery.failed and token.invalid for an
update or end push, it has installId, activityKitId, status, hasPushToken, sentVersion and updatedAt. In
token.invalid for a start push it is { installId } only.
error is a reason string: no_push_to_start_token (no device of that user could start it), start_rejected (Apple
refused the start on every device), Apple’s own reason such as BadDeviceToken or Unregistered, or status_<code> when Apple gave no reason.
Example, activity.started:
{
"id": "evt_3q8Zr1mX0aKd7wYp5LbT2g",
"type": "activity.started",
"createdAt": 1795180003000,
"data": {
"activity": {
"id": "act_8f2c61d0b7a94e3f9a1c2d3e4f5a6b7c",
"appId": "3f0c9a52-6d1e-4b7a-8c25-0e9d4f1a7b36",
"userId": "user_42",
"installId": null,
"attributesType": "DeliveryAttributes",
"attributes": { "orderId": "1234" },
"contentState": { "eta": 15, "status": "cooking" },
"status": "active",
"startAt": 1795180000000,
"staleDate": null,
"endedAt": null,
"version": 0,
"createdAt": 1795179990000
},
"target": { "installId": "6B1F7C2E-…", "activityKitId": "A1B2C3D4-…", "status": "active" }
}
}
Example, token.invalid (the activity object is as above):
{
"id": "evt_Qm2vN8cK5xRt1pLw9YdE4a",
"type": "token.invalid",
"createdAt": 1795180410000,
"data": {
"activity": { "id": "act_8f2c…", "status": "active", "…": "…" },
"target": { "installId": "6B1F7C2E-…", "activityKitId": "A1B2C3D4-…", "status": "active", "hasPushToken": true, "sentVersion": 2, "updatedAt": 1795180004000 },
"error": "BadDeviceToken"
}
}
The test event from Send test event has type: "test" and data: { app: { id, name } }.
Verify the signature
Every request carries
LAC-Signature: t=<unix ms>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
Compute the HMAC over the raw request body (not re-serialized JSON) with your signing secret, and compare it in constant time.
import crypto from "node:crypto";
export function verify(header: string, rawBody: string, secret: string) {
const [t, v1] = header.split(",").map((part) => part.split("=")[1]);
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const a = Buffer.from(v1 ?? "");
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
To also reject replays, check that t is close to the current time. t is set when we send, so a retry carries a
fresh one.
Retries
Any answer other than 2xx, a timeout or a network error is retried with backoff: after 30 seconds, 2 minutes,
8 minutes, 32 minutes and 60 minutes. After that the event is dropped. A retry has the same id, so use it to
ignore duplicates. Events can arrive out of order, so use activity.version and createdAt if order matters.