Introducing LiveActivityRead more

Guides / WebhooksMenu

Webhooks

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

Updated · Markdown · Ask Claude · Ask ChatGPT

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:

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