# Webhooks

> Events we send to your backend, and how to verify them.

Updated 2026-11-21

Webhooks tell your backend what happened on the phones: an activity started, got a new token, ended, or Apple
refused a push.

## Set up

1. Open your app in the dashboard, tab **Webhooks**.
2. Enter an `https://` URL and save. Leave it empty to turn webhooks off.
3. 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:

```json
{
  "id": "evt_3q8Zr1mX0aKd7wYp5LbT2g",
  "type": "activity.started",
  "createdAt": 1795180003000,
  "data": { "activity": { … }, "target": { … } }
}
```

`data.activity` is the [activity object](/docs/api#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`:

```json
{
  "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):

```json
{
  "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.

```ts
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.
