# Webhooks

> Webhook endpoints over the server API: create, list, change, delete, rotate the secret and ping, plus the delivery request, every event type and its payload, signature verification, retries and auto-disable.

Source: https://docs.getbeekon.com/api/webhooks/

A **webhook endpoint** receives your project’s [events](https://docs.getbeekon.com/api/events/) at an HTTPS URL you own, as they happen. Create one, [verify each delivery’s signature](#verifying-the-signature) and answer `2xx`. A project can have up to **10** endpoints.

“Endpoint” is the console’s word, and these pages use it too. In the API the object is a `webhook`, its URL is `endpoint_url`, and deliveries name it in the `Beekon-Subscription` header.

## POST `/v1/webhooks`

**Scope:** `webhooks:write` · Creates a webhook endpoint. Its status starts `active`.

```sh
curl -s -X POST https://api.in1.getbeekon.com/v1/webhooks \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://hooks.example.com/beekon",
    "event_types": ["geofence.enter", "geofence.exit"]
  }'
```

| Member         | Type                        | Required | Rule                                                                                                                         |
| -------------- | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `endpoint_url` | string                      | yes      | See [Endpoint URLs](#endpoint-urls).                                                                                         |
| `event_types`  | array of strings, or `null` | no       | A non-empty list of [event types](#event-types), matched exactly. Absent or `null`: every type, including types added later. |

**Response** `201`, with `Cache-Control: no-store`:

```jsonc
{"secret": "whsec_…", "webhook": {…}}
```

The secret is shown once

Store `secret` now. No call returns it again. If you lose it, [rotate](#rotate-the-secret).

A project’s 11th endpoint is `409 webhook_limit_reached`. Disabled endpoints count. Creating is not idempotent: after a timeout, list your endpoints before retrying.

## The delivery request

Each delivery is one `POST` to your endpoint:

```plaintext
POST /your/webhook/path HTTP/1.1
Content-Type: application/json
Beekon-Delivery: 0192…       (unique per attempt — for tracing only)
Beekon-Subscription: 3f1c…   (which webhook endpoint — use it to pick the secret)
Beekon-Project: 0199…        (which project — use it to pick the secret)
Beekon-Signature: t=1791354600,v1=<64 lowercase hex characters>


{"events":[{…},{…}],"schema_version":1}
```

Each item in `events` is one [event object](#event-payloads).

* The body carries **1 to 100** events, in no particular order. Beekon keeps a body within 1 MiB, except that a single event larger than that is sent on its own. Handle more than one event per request, and deduplicate per event `id`, never per request.
* `Beekon-Subscription` and `Beekon-Project` exist so one URL can serve several endpoints; use them only to choose which secret to verify with, and trust nothing else in the request until the signature verifies.
* Beekon never follows redirects. A `3xx` response counts as a failed attempt.

## Event types

Every delivery’s `events` array holds event objects of these types. They are the same objects [`GET /v1/events`](https://docs.getbeekon.com/api/events/) returns.

| `type`                    | Produced when                                                                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `geofence.enter`          | The server confirms that a device entered a geofence. See [Geofence events](#geofence-events).                                                |
| `geofence.exit`           | The server confirms that a device left a geofence, or, for a fence set to `on_unreachable: exit`, that a device inside it became unreachable. |
| `geofence.dwell`          | A device stayed inside a geofence for 5 minutes, the one dwell time.                                                                          |
| `trip.started`            | A device’s trip was first stored. See [Trip events](#trip-events).                                                                            |
| `trip.stalled`            | An open trip’s device went quiet.                                                                                                             |
| `trip.ended`              | A stored trip was first closed.                                                                                                               |
| `device.unreachable`      | A device with a fence visit or a trip in progress stopped being reachable. See [Device presence events](#device-presence-events).             |
| `device.reachable`        | That device was heard from again.                                                                                                             |
| `billing.usage_threshold` | The project’s monthly active users (MAU) crossed 50%, 80% or 100% of your configured cap. An alert: usage goes on past the cap.               |
| `webhook.ping`            | You asked for a [test delivery](https://docs.getbeekon.com/api/webhooks/#send-a-test-ping). Webhooks only: never stored, never in `GET /v1/events`.                     |

New types may be added. **Skip an event whose `type` you don’t know**: never fail the page or the webhook delivery because of it. A webhook endpoint with `event_types: null` receives every type, including types added later.

`event_types` on an endpoint takes any of these except `webhook.ping`: a ping goes only to the endpoint you [ping](#send-a-test-ping), whatever its `event_types`. Any other value is `400 invalid_event_types`. An endpoint with `event_types: null` receives every type, including types added later, so make sure your handler skips types it doesn’t know. To keep an endpoint on the types it handles, give it an explicit list.

## Event payloads

Each object in a delivery’s `events` array is one of the shapes below. Every event has `id` (your deduplication key), `type`, `occurred_at` and `project_id`; the rest depends on the type.

### Geofence events

The server decides geofence events from the device’s uploaded locations, by the rules in [What produces a geofence event](https://docs.getbeekon.com/api/geofences/#what-produces-a-geofence-event). A crossing the device notices while tracking is stopped still notifies on the device, but the server has no locations for it, so it records no event. The exception is a fence set to [`on_unreachable: exit`](https://docs.getbeekon.com/api/geofences/#fence-policies), which can send an exit when the device stops tracking inside it. See [Geofencing](https://docs.getbeekon.com/guide/geofencing/#geofences-in-beekon-cloud).

An enter confirmed by the device’s locations:

```json
{
  "id": "019e9f61-1400-7000-8000-0000000000e1",
  "type": "geofence.enter",
  "detected_at": "2026-06-07T00:00:02.000Z",
  "device": {"install_id": "install-e1", "user_id": "acct_9931"},
  "evidence": "track",
  "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"},
  "location": {
    "accuracy_m": 12.5,
    "latitude": 12.9716,
    "longitude": 77.5946,
    "recorded_at": "2026-06-07T00:00:00.000Z"
  },
  "occurred_at": "2026-06-07T00:00:00.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1"
}
```

A dwell, five minutes after that enter. `dwell_seconds` is the threshold that was crossed, and `location` is the latest location inside the fence:

```json
{
  "id": "019e9f65-ee00-7000-8000-0000000000e5",
  "type": "geofence.dwell",
  "detected_at": "2026-06-07T00:05:02.000Z",
  "device": {"install_id": "install-e1", "user_id": "acct_9931"},
  "dwell_seconds": 300,
  "evidence": "track",
  "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"},
  "location": {
    "accuracy_m": 10,
    "latitude": 12.9717,
    "longitude": 77.5947,
    "recorded_at": "2026-06-07T00:04:50.000Z"
  },
  "occurred_at": "2026-06-07T00:05:00.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1"
}
```

An exit sent because the device became unreachable inside a fence set to `on_unreachable: exit`. It has no `location`, and the exit happened between `occurred_after` and `occurred_at`:

```json
{
  "id": "019ea0c2-5b00-7000-8000-0000000000e2",
  "type": "geofence.exit",
  "detected_at": "2026-06-07T02:00:41.000Z",
  "device": {"install_id": "install-e1", "user_id": "acct_9931"},
  "evidence": "unreachable",
  "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"},
  "occurred_after": "2026-06-06T13:59:58.000Z",
  "occurred_at": "2026-06-07T02:00:00.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1"
}
```

An enter the SDK reported itself, confirmed at once by a location in the same upload:

```json
{
  "id": "019ea2a4-1c00-7000-8000-0000000000e3",
  "type": "geofence.enter",
  "detected_at": "2026-06-07T08:30:03.000Z",
  "device": {"install_id": "install-e1", "user_id": "acct_9931"},
  "evidence": "corroborated",
  "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"},
  "location": {
    "accuracy_m": 18,
    "latitude": 12.9717,
    "longitude": 77.5945,
    "recorded_at": "2026-06-07T08:29:40.000Z"
  },
  "occurred_at": "2026-06-07T08:29:40.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1"
}
```

The enter of a drive-through on a fence set to `pass_through: on`. Neither location was inside; `occurred_at` is where the line between them went in, so it is before `location.recorded_at`. Its `geofence.exit` carries the same `location`:

```json
{
  "id": "019ea2c5-7e00-7000-8000-0000000000e4",
  "type": "geofence.enter",
  "detected_at": "2026-06-07T09:05:21.000Z",
  "device": {"install_id": "install-e1", "user_id": "acct_9931"},
  "evidence": "interpolated",
  "geofence": {"id": "019000f0-0000-7000-8000-0000000000f2"},
  "location": {
    "accuracy_m": 8,
    "latitude": 12.9741,
    "longitude": 77.6012,
    "recorded_at": "2026-06-07T09:05:00.000Z"
  },
  "occurred_at": "2026-06-07T09:04:52.300Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1"
}
```

| Field            | Type    | Presence                               | Meaning                                                                                                                                                                                                                                                 |
| ---------------- | ------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | string  | always                                 | The event id (a UUIDv7). **Your deduplication key**: a redelivered event keeps its `id`.                                                                                                                                                                |
| `type`           | string  | always                                 | `geofence.enter`, `geofence.exit` or `geofence.dwell`.                                                                                                                                                                                                  |
| `occurred_at`    | string  | always                                 | When the crossing happened, not when it was evaluated or delivered. Which instant depends on `evidence` (table below); for a dwell, the instant the dwell time was reached.                                                                             |
| `detected_at`    | string  | always                                 | When the server produced the event, on the server’s clock. At or after `occurred_at`, unless the device’s clock ran ahead of the server’s. Far after it for a `late` event or an upload that arrived late.                                              |
| `project_id`     | string  | always                                 | Your project.                                                                                                                                                                                                                                           |
| `device`         | object  | always                                 | `install_id` (always) · `user_id` (when the triggering location carried one) · `session_id` (when set). For an `unreachable` exit, the triggering location is the last one inside the fence.                                                            |
| `geofence`       | object  | always                                 | `id`, the geofence’s id. An `external_id` member is reserved: it appears only for a fence authored with one, which no endpoint offers yet.                                                                                                              |
| `evidence`       | string  | always                                 | What the server’s decision rests on: `track`, `interpolated`, `corroborated` or `unreachable` (table below). Read a value you don’t know as “decided by the server, evidence unknown”.                                                                  |
| `location`       | object  | always, except `evidence: unreachable` | The triggering location: `latitude`, `longitude`, `recorded_at`, and `accuracy_m` when the location had an accuracy. For a dwell, the latest location inside the fence when the dwell time was reached. Absent (never `null`) on an `unreachable` exit. |
| `occurred_after` | string  | `unreachable` exits only               | The recorded time of the device’s last location inside the fence. The exit happened after it and at or before `occurred_at`.                                                                                                                            |
| `late`           | boolean | only as `true`                         | The event belongs to a complete visit rebuilt from locations that arrived late. It never describes where the device is now. See [late locations](#late-locations).                                                                                      |
| `dwell_seconds`  | number  | dwell only                             | The dwell threshold that was crossed (not the total stay): `300` today, the same for every project.                                                                                                                                                     |

**Evidence**

| `evidence`     | Meaning                                                                                                                                                      | `location`                                                  | `occurred_at`                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `track`        | The device’s admitted locations alone confirmed it.                                                                                                          | The confirming location (dwell: the latest location inside) | The confirming location’s recorded time (dwell: when the dwell time was reached) |
| `corroborated` | The device reported the crossing itself, and an admitted location in the same upload that does not contradict it confirmed it at once.                       | That location                                               | That location’s recorded time                                                    |
| `interpolated` | A pass-through: two consecutive locations outside the fence whose straight line crosses it. Only for a fence with `pass_through: on`.                        | The first location after the crossing                       | An instant between the two locations, so before `location.recorded_at`           |
| `unreachable`  | The device was confirmed inside, then became [unreachable](#device-presence-events). `geofence.exit` only, and only for a fence with `on_unreachable: exit`. | absent                                                      | The `occurred_at` of the `device.unreachable` that caused it                     |

A project whose fences all keep the default policies (`pass_through: off`, `on_unreachable: none`) never receives `interpolated` or `unreachable`, so every geofence event it receives has a `location`. See [fence policies](https://docs.getbeekon.com/api/geofences/#fence-policies).

* **Dwell.** At most one `geofence.dwell` per visit. There is one threshold, and it is not configurable; another dwell needs an exit first. A dwell can fire for a device that has stopped sending locations, so its `location.recorded_at` can be well before `occurred_at`. It is not sent for a device that became unreachable before the dwell time was reached, nor while its visit is unverified (see [fence policies](https://docs.getbeekon.com/api/geofences/#fence-policies)).
* **The device’s own crossings** never produce an event alone. They only let an admitted location confirm a crossing at once (`corroborated`), never against a location that contradicts them.

#### Late locations

A location is **late** when it is recorded before the newest location the server has already evaluated for that device, for example when an offline device uploads its backlog after newer locations. Late locations never change the device’s current state in a fence.

When late locations recorded within 72 hours before the newest evaluated location show a **complete visit** (an enter and an exit of the same fence) that does not overlap a visit already sent, Beekon sends both events with `late: true`. An incomplete visit sends nothing, a late visit never produces a dwell, and locations more than 72 hours behind produce no events. All late locations are stored and readable on [`GET /v1/locations`](https://docs.getbeekon.com/api/locations/).

### Trip events

Beekon produces trip events on the server, from the same trip detection as [`GET /v1/trips`](https://docs.getbeekon.com/api/trips/). The SDK needs no change.

A `trip.started`, for a trip that is still open:

```json
{
  "id": "01a11597-4e80-7a3c-9d21-6b5e4f3a2c10",
  "type": "trip.started",
  "detected_at": "2026-10-07T09:00:34.000Z",
  "device": {
    "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
    "user_id": "acct_9931"
  },
  "occurred_at": "2026-10-07T09:00:00.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1",
  "trip": {
    "id": "5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f",
    "distance_m": 182.4,
    "duration_seconds": 30,
    "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
    "last_point_at": "2026-10-07T09:00:30.000Z",
    "mode": "driving",
    "mode_counts": {"driving": 3},
    "point_count": 3,
    "revision": 1,
    "settings_revision": 7,
    "start": {"latitude": 12.9716, "longitude": 77.5946},
    "started_at": "2026-10-07T09:00:00.000Z",
    "status": "open",
    "user_id": "acct_9931"
  }
}
```

The `trip.ended` for the same trip:

```json
{
  "id": "01a115a8-6d50-7b4d-8e32-7c6f5a4b3d21",
  "type": "trip.ended",
  "detected_at": "2026-10-07T09:18:44.000Z",
  "device": {
    "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
    "user_id": "acct_9931"
  },
  "occurred_at": "2026-10-07T09:18:42.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1",
  "trip": {
    "id": "5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f",
    "distance_m": 5234.81,
    "duration_seconds": 1122,
    "end": {"latitude": 12.9352, "longitude": 77.6245},
    "end_reason": "stop",
    "ended_at": "2026-10-07T09:18:42.000Z",
    "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
    "last_point_at": "2026-10-07T09:18:42.000Z",
    "mode": "driving",
    "mode_counts": {"driving": 41, "still": 3, "walking": 2},
    "point_count": 46,
    "revision": 2,
    "settings_revision": 7,
    "start": {"latitude": 12.9716, "longitude": 77.5946},
    "started_at": "2026-10-07T09:00:00.000Z",
    "status": "closed",
    "user_id": "acct_9931"
  }
}
```

A `trip.stalled` for another trip, whose device went quiet at 14:02 and stayed silent for the default 600 seconds:

```json
{
  "id": "01a11702-91c0-7e4a-8b16-2d3c4b5a6f70",
  "type": "trip.stalled",
  "detected_at": "2026-10-07T14:12:31.000Z",
  "device": {
    "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
    "user_id": "acct_9931"
  },
  "occurred_at": "2026-10-07T14:01:55.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1",
  "trip": {
    "id": "7c1e4d8f-3a2b-8d5e-9f60-1b2c3d4e5f6a",
    "distance_m": 3120.5,
    "duration_seconds": 715,
    "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50",
    "last_point_at": "2026-10-07T14:01:55.000Z",
    "mode": "driving",
    "mode_counts": {"driving": 28, "walking": 1},
    "point_count": 29,
    "revision": 4,
    "settings_revision": 7,
    "start": {"latitude": 12.9352, "longitude": 77.6245},
    "started_at": "2026-10-07T13:50:00.000Z",
    "status": "stalled",
    "user_id": "acct_9931"
  }
}
```

| Field         | Type   | Presence | Meaning                                                                                                                                                                                                                                                              |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string | always   | The event id (a UUIDv7). Your deduplication key.                                                                                                                                                                                                                     |
| `type`        | string | always   | `trip.started`, `trip.stalled` or `trip.ended`.                                                                                                                                                                                                                      |
| `occurred_at` | string | always   | The trip’s own time on the device’s timeline: its `started_at` (started), `last_point_at` (stalled: the last thing the device recorded before it went quiet) or `ended_at` (ended). Not when the event was produced or delivered.                                    |
| `detected_at` | string | always   | When the server produced the event, on the server’s clock. For `trip.stalled`, at least `silence_timeout_seconds` after the device’s last contact, unless the device was declared unreachable sooner.                                                                |
| `project_id`  | string | always   | Your project.                                                                                                                                                                                                                                                        |
| `device`      | object | always   | `install_id` (always) · `user_id` (when the trip has one).                                                                                                                                                                                                           |
| `trip`        | object | always   | The [trip object](https://docs.getbeekon.com/api/trips/#the-trip-object), exactly as `GET /v1/trips/{trip_id}` returned it when the event was produced: `status` `open` (or `closed`, for a trip that arrived whole) on `trip.started`, `stalled` on `trip.stalled`, `closed` on `trip.ended`. |

**When they fire.**

* **`trip.started`** fires once, when the trip is first stored. A trip is stored at its third location, so the event arrives after the trip began: `occurred_at` is often minutes before you receive it.
* **`trip.stalled`** fires once per stall, when an open trip’s device has had no contact for `silence_timeout_seconds` (default: the effective `max_gap_seconds`, 600 seconds unless you changed it), or as soon as the device is declared unreachable. A trip can stall more than once: new locations return it to `open` (with no event), and a later silence stalls it again at a higher `trip.revision`. See [the trip lifecycle](https://docs.getbeekon.com/api/trips/#the-trip-lifecycle).
* **`trip.ended`** fires exactly once, when a stored trip first becomes `closed`, from `open` or `stalled`. It is final. A device that uploads a whole trip at once, for example after being offline, produces `trip.started` and `trip.ended` together.
* A trip event is never produced twice for the same trip and type (for `trip.stalled`, the same trip, type and revision), even when the server retries its work.

**When `trip.ended` arrives**, with the default settings:

| What happened                                                    | `trip.stalled`                   | `trip.ended`                                    | `end_reason`                                          |
| ---------------------------------------------------------------- | -------------------------------- | ----------------------------------------------- | ----------------------------------------------------- |
| The app called `stop()`                                          | none                             | within seconds in `in1`, later in other regions | `tracking_stopped`                                    |
| The device stopped, GPS kept on                                  | none                             | about `stop_duration_seconds` after it arrived  | `stop`                                                |
| The device stopped and paused GPS, SDK 0.6.0 or later            | none                             | when the SDK declares the rest                  | `stop`                                                |
| The device stopped and paused GPS, SDK 0.5.0 or earlier          | after 10 minutes without contact | at its next check-in or departure               | `stop`                                                |
| The app was killed, the battery died, or the app was uninstalled | after 10 minutes without contact | after `finality_timeout_seconds` (24 hours)     | `silence`                                             |
| Offline for 30 minutes while driving, then uploads               | after 10 minutes without contact | when the real stop is confirmed                 | `stop`                                                |
| Offline for longer than `finality_timeout_seconds` while driving | after 10 minutes without contact | after `finality_timeout_seconds`                | `silence`; the rest of the journey becomes a new trip |

**Rules for your integration.**

* **`trip.ended` is final for its trip id.** Delivery is unordered, so a `trip.stalled` can arrive after it: ignore a `trip.stalled` for a trip you have already seen end.
* **Between two `trip.stalled` events for one trip, the higher `trip.revision` wins.**
* **Subscribe to `trip.stalled` only if you can act on “probably ended”** and reconcile when `trip.ended` brings the real end. An endpoint that takes only `trip.ended` is never handed a guess. Choose with the endpoint’s `event_types`.
* **A `trip.ended` can come without a `trip.started`.** A trip that was already open when trip events were switched on in its region (see the [changelog](https://docs.getbeekon.com/api/changelog/)) ends without a start. So can a trip whose id a [rebuild](https://docs.getbeekon.com/api/trips/#rebuilds) changed. A `trip.ended` can also be delivered before its `trip.started`.
* **The `trip` member is a snapshot.** It does not change after the event is produced. Read [`GET /v1/trips/{trip_id}`](https://docs.getbeekon.com/api/trips/#get-v1tripstrip_id) for the trip as it is now.
* **Some changes send nothing.** A return from `stalled` to `open` sends nothing, and neither does a late location that changes a closed trip, a [rebuild](https://docs.getbeekon.com/api/trips/#rebuilds), retention or data erasure.

### Device presence events

The server keeps track of whether it still hears from each device running the SDK in cloud mode. When a device that has something in progress (it is confirmed inside one of your geofences, or has an open or stalled trip) stops being reachable, Beekon sends `device.unreachable`. When the device is heard from again, it sends `device.reachable`.

A device on a trip whose app was killed, declared unreachable when the 12-hour rest limit passed:

```json
{
  "id": "019000ee-0000-7000-8000-0000000000a1",
  "type": "device.unreachable",
  "detected_at": "2026-06-07T02:00:41.000Z",
  "device": {
    "install_id": "9f1b6c2e-8d4a-4b7f-9c3d-2e1f0a9b8c7d",
    "user_id": "customer-42"
  },
  "occurred_at": "2026-06-07T02:00:00.000Z",
  "presence": {
    "context": {
      "geofences": [{"id": "019000f0-0000-7000-8000-0000000000f1"}],
      "trip_id": "3e9a7b1c-5d2f-8a4e-9b60-7c8d9e0f1a2b"
    },
    "last_contact_at": "2026-06-06T14:00:00.000Z",
    "last_fix": {
      "accuracy_m": 9.5,
      "latitude": 12.9716,
      "longitude": 77.5946,
      "recorded_at": "2026-06-06T13:59:58.000Z"
    },
    "reason": "rest_limit"
  },
  "project_id": "019000b0-0000-7000-8000-0000000000b1"
}
```

The `device.reachable` that ends the same episode:

```json
{
  "id": "019000ee-0000-7000-8000-0000000000a2",
  "type": "device.reachable",
  "detected_at": "2026-06-07T03:40:05.000Z",
  "device": {
    "install_id": "9f1b6c2e-8d4a-4b7f-9c3d-2e1f0a9b8c7d",
    "user_id": "customer-42"
  },
  "occurred_at": "2026-06-07T03:40:04.000Z",
  "presence": {
    "context": {"geofences": []},
    "last_contact_at": "2026-06-06T14:00:00.000Z",
    "last_fix": {
      "accuracy_m": 9.5,
      "latitude": 12.9716,
      "longitude": 77.5946,
      "recorded_at": "2026-06-06T13:59:58.000Z"
    },
    "unreachable_event_id": "019000ee-0000-7000-8000-0000000000a1"
  },
  "project_id": "019000b0-0000-7000-8000-0000000000b1"
}
```

| Field                           | Type    | Presence                                  | Meaning                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------- | ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                            | string  | always                                    | The event id (a UUIDv7). Your deduplication key.                                                                                                                                                                                                                                                                                                      |
| `type`                          | string  | always                                    | `device.unreachable` or `device.reachable`.                                                                                                                                                                                                                                                                                                           |
| `occurred_at`                   | string  | always                                    | On the server’s clock. `device.unreachable`: the deadline that passed (`silent_while_moving`, `rest_limit`), or when the server received the upload that reported the stop or the lost permission (`tracking_stopped`, `permission_lost`). `device.reachable`: when the server received the upload that ended the silence.                            |
| `detected_at`                   | string  | always                                    | When the server produced the event, at or after `occurred_at`. For a deadline, the difference is the check’s lag: normally under a minute in the `in1` region, and later in other regions.                                                                                                                                                            |
| `project_id`                    | string  | always                                    | The project of the device’s last accepted upload.                                                                                                                                                                                                                                                                                                     |
| `device`                        | object  | always                                    | `install_id` (always) · `user_id` (when the device’s newest admitted location carried one).                                                                                                                                                                                                                                                           |
| `presence.reason`               | string  | `device.unreachable` only                 | Why the device is unreachable (table below). Read a value you don’t know as “unreachable, reason unknown”.                                                                                                                                                                                                                                            |
| `presence.probe_unanswered`     | boolean | only as `true`, `device.unreachable` only | The server sent the device a push probe during this silence and no answer arrived. Not produced until the probe is on: see [the push probe](#the-push-probe).                                                                                                                                                                                         |
| `presence.last_contact_at`      | string  | always                                    | When the server last received an upload from the device before the silence. On `device.reachable` it repeats the `device.unreachable`’s value, so `last_contact_at` and `occurred_at` bound the silent window.                                                                                                                                        |
| `presence.last_fix`             | object  | when the device ever sent a location      | The device’s newest admitted location: `latitude`, `longitude`, `recorded_at`, and `accuracy_m` when it had an accuracy.                                                                                                                                                                                                                              |
| `presence.context`              | object  | always                                    | What the device had in progress when the event was produced: `geofences` (always; every fence it is confirmed inside, as `{id}`, in ascending `id` order, possibly empty; as in geofence events, an `external_id` member is reserved for fences authored with one, which no endpoint offers yet) and `trip_id` (when it has an open or stalled trip). |
| `presence.unreachable_event_id` | string  | `device.reachable` only                   | The `id` of the `device.unreachable` that opened this episode.                                                                                                                                                                                                                                                                                        |

| `reason`              | When                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `silent_while_moving` | A moving device sent nothing past its deadline.                                            |
| `rest_limit`          | A resting device sent nothing for longer than the project’s `presence.rest_limit_seconds`. |
| `tracking_stopped`    | The app called `stop()` while the device was inside a fence or on a trip.                  |
| `permission_lost`     | The device reported that location permission was taken away or location was switched off.  |

**What counts as hearing from a device.** Every upload the server accepts from the SDK on that device counts as **contact**, including a heartbeat or an upload with no locations. Config fetches, refused uploads and uploads you make with a server key through [`POST /v1/ingest`](https://docs.getbeekon.com/api/ingest/) do not. A device whose locations reach Beekon only through server-key uploads produces no presence events.

**The deadlines.** After each contact the server sets a deadline from what the device reported:

| The device is                         | Deadline after its last contact                                                                                                                                                                                                                                       |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Moving**                            | Twice its upload interval, plus 120 seconds. The interval is the larger of `sync.interval_seconds` and the platform’s floor: 900 seconds on Android, 60 seconds on iOS. With the default 300-second interval, that is 720 seconds on iOS and 1920 seconds on Android. |
| **Resting**                           | `presence.rest_limit_seconds` from your [remote config](https://docs.getbeekon.com/api/remote-config/#presence), 43200 seconds (12 hours) by default.                                                                                                                                           |
| **Stopped** (the app called `stop()`) | None: the server waits for it to start again.                                                                                                                                                                                                                         |

**Devices on SDK 0.5.0 and earlier count as resting.** A device is moving or resting by what its SDK says. SDK 0.6.0 and later say when the device is resting, so a device on 0.6.0 that tracks without declaring rest is moving. SDK 0.5.0 and earlier can’t say it, so those devices are treated as resting while they track: the moving deadline and `silent_while_moving` don’t apply to them, and one whose app is killed while it moves is declared unreachable only when the rest limit passes (12 hours by default).

* A project whose `tracking.when_stationary` is `reduce` or `keep` has every device treated as resting, whatever the SDK, because its devices may send nothing for hours by design.
* `heartbeat_interval_seconds` doesn’t shorten the resting deadline, but each heartbeat is contact and moves the deadline forward.
* The server checks deadlines every minute. `occurred_at` is the deadline itself, and `detected_at` shows how late the check ran: punctual in the `in1` region, later in other regions.

**When an event is sent.**

* **Only for a device with something in progress.** A device becomes unreachable whether or not it has a fence visit or a trip, but the event is sent only if it is confirmed inside at least one fence or has an open or stalled trip at that moment. Phones switched off overnight with nothing in progress send nothing. `tracking_stopped` and `permission_lost` make such a device unreachable only when it has something in progress.
* **One episode, at most two events.** An episode runs from the moment the device becomes unreachable to its next contact. It produces at most one `device.unreachable` and one `device.reachable`. A `device.reachable` is sent only if the episode’s `device.unreachable` was sent, whatever the device has in progress when it returns.
* **Unordered.** A `device.reachable` can arrive before its `device.unreachable`. Pair them by `presence.unreachable_event_id`.

**What it means.** A `device.unreachable` is a fact on the server’s clock and is never retracted: the server heard nothing before the deadline, or the device said it can no longer track. It says nothing about where the device is: a phone whose battery died or whose app was force-stopped can’t be located. The server reports it `unreachable` when its deadline passes: the moving deadline for a moving device on SDK 0.6.0 or later, otherwise after 12 hours by default, and later than that outside the `in1` region. What happens to the device’s fence visits and trips is sent as separate events: a fence’s [`on_unreachable`](https://docs.getbeekon.com/api/geofences/#fence-policies) policy decides whether you get a `geofence.exit` with `evidence: unreachable`, and an open trip [stalls](https://docs.getbeekon.com/api/trips/#the-trip-lifecycle) with a `trip.stalled`.

#### The push probe

Off until the region enables it

The probe is switched off. No project can turn it on until its region enables the probe, and push credentials must also be connected to your project. A device can answer only with SDK 0.6.0 or later, in an app that hands Beekon its push token: Android `Beekon.setPushToken` and `Beekon.handlePushMessage`, iOS `startMonitoringLocationPushes(appGroup:)` and a Location Push Service Extension (see the [SDK 0.6.0 changelog](https://docs.getbeekon.com/api/changelog/#sdk-060)). Until then, no event carries `probe_unanswered`.

How the probe works once it is on

Before it declares a silent device unreachable, the server can send it one push message with your app’s own push credentials and wait 120 seconds for an answer. An answer is ordinary contact, so no event is sent. Without an answer, the `device.unreachable` carries `probe_unanswered: true`. At most one probe is sent per device per hour, and only for the two deadline reasons. The probe is optional and off by default; when it is on for your project, the server sets `features.presence_probe` in the config devices receive, and you cannot set that flag yourself (see [Remote config](https://docs.getbeekon.com/api/remote-config/#the-reserved-presence_probe-flag)).

### Usage threshold events

```json
{
  "id": "019ecb27-2200-7000-8000-0000000000b8",
  "type": "billing.usage_threshold",
  "occurred_at": "2026-06-15T12:00:00.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1",
  "usage": {
    "cap_mtu": 100,
    "month": 6,
    "mtu": 85,
    "threshold": 80,
    "year": 2026
  }
}
```

| Field         | Type   | Meaning                                                                                                                                                                                           |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string | The event id; one per project, month and threshold, ever.                                                                                                                                         |
| `type`        | string | `billing.usage_threshold`.                                                                                                                                                                        |
| `occurred_at` | string | When the month’s count crossed the threshold.                                                                                                                                                     |
| `project_id`  | string | Your project.                                                                                                                                                                                     |
| `usage`       | object | `cap_mtu` (your monthly active user cap) · `mtu` (the monthly active user count at the crossing) · `threshold` (`50`, `80` or `100`, percent of the cap) · `month` (1–12) · `year`. All integers. |

A usage event has no `device`, `geofence`, `location` or `detected_at`. Each threshold fires at most once per calendar month (UTC); raising your cap does not re-arm a threshold already crossed that month. The events are the cap’s alert, not a stop: after the 100% event, new users are still admitted and counted. See [the MAU cap](https://docs.getbeekon.com/cloud/usage/#usage-and-the-mau-cap).

### Ping events

```json
{
  "id": "01a1150d-fa40-7c2d-8e3f-405162738495",
  "type": "webhook.ping",
  "occurred_at": "2026-10-07T06:30:00.000Z",
  "project_id": "019000b0-0000-7000-8000-0000000000b1"
}
```

A `webhook.ping` has only `id`, `type`, `occurred_at` (when the ping was made) and `project_id`. It reaches only the webhook endpoint that was pinged, is never retried, and never appears in `GET /v1/events`. Acknowledge it with a `2xx` like any delivery.

## Verifying the signature

Every delivery carries a `Beekon-Signature` header. Check it before you trust the body:

```plaintext
Beekon-Signature: t=1730448000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

1. Take the **raw request body**, before any JSON parsing.
2. Reject the delivery if `t` is more than **5 minutes** from your clock.
3. Compute an HMAC-SHA256 of `t`, a `.`, and the raw body, keyed with your endpoint’s secret, and compare it with `v1` in constant time.

```js
// Node.js — rawBody is a Buffer (e.g. express.raw({ type: 'application/json' }))
import crypto from 'node:crypto';


export function isFromBeekon(rawBody, header, secret) {
  const parts = header.split(',').map((p) => p.split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(`${t}.`).update(rawBody).digest('hex');
  return parts.some(([k, v]) => k === 'v1' && v.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
}
```

```python
# Python — raw_body is bytes (e.g. request.get_data() in Flask)
import hashlib, hmac, time


def is_from_beekon(raw_body: bytes, header: str, secret: str) -> bool:
    parts = [p.split("=", 1) for p in header.split(",")]
    t = next((v for k, v in parts if k == "t"), None)
    if t is None or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)
```

A header can hold more than one `v1`: right after you [rotate the secret](#secret-rotation), deliveries are signed with both the new and the previous secret. While you switch over, accept a delivery if it verifies with **either** secret.

### A complete receiver

An Express handler that verifies the signature, skips redeliveries and event types it doesn’t handle, and acknowledges the delivery. It uses `isFromBeekon` from above.

```js
import express from 'express';
import { isFromBeekon } from './beekon-signature.js'; // the function above


const app = express();
const secret = process.env.BEEKON_WEBHOOK_SECRET; // whsec_…, from POST /v1/webhooks
// Stand-in for your database: in production, insert each event id into a
// table with a unique index, and skip the event when the insert conflicts.
const seen = new Set();


// Take the raw bytes: the signature covers the body exactly as sent.
app.post('/beekon', express.raw({ type: 'application/json' }), (req, res) => {
  if (!isFromBeekon(req.body, req.get('Beekon-Signature') ?? '', secret)) {
    return res.sendStatus(401);
  }
  const { events, schema_version } = JSON.parse(req.body.toString('utf8'));
  // A format you don't understand: answer non-2xx so Beekon keeps the events.
  if (schema_version !== 1) return res.sendStatus(500);


  for (const event of events) {
    if (seen.has(event.id)) continue; // a redelivery
    seen.add(event.id);
    if (event.type === 'geofence.enter' || event.type === 'geofence.exit') {
      console.log(event.type, event.geofence.id, event.device.install_id, event.occurred_at);
    }
    // Skip other types, including ones Beekon adds later.
  }
  res.sendStatus(200); // acknowledges every event in this delivery
});


app.listen(8080);
```

### Secret rotation

An endpoint holds at most two secrets, the newest and the one before it.

1. Rotate, then add the new secret to your verifier next to the old one.
2. Keep accepting the old secret for a few minutes: deliveries already on their way, and retries, may still be signed only with it.
3. Once real deliveries verify with the new secret, remove the old one. A test ping doesn’t count: it can be signed with the new secret before real deliveries are.

If a secret has leaked, rotate with `{"expire_previous": true}`: from the next delivery on, only the new secret signs, so switch your verifier straight away.

## Responding and retries

* **Answer `2xx` to acknowledge** the whole delivery. Anything else — any other status, a redirect, a timeout (30 s) or a connection failure — is a failed attempt and will be retried.
* Retries back off exponentially (the first within a minute, then at least 1.5× longer each time, at most an hour apart) for **at least 24 hours**. Each retry is signed afresh with a new `t`.
* Delivery is **at least once** and **unordered**. Deduplicate on the event `id`, atomically — deliveries to one endpoint can arrive concurrently.
* If you receive a body whose `schema_version` you don’t understand, answer non-`2xx` so the events are kept, rather than acknowledging data you couldn’t read. Unknown event **types**, by contrast, should be skipped and acknowledged.
* [`GET /v1/events`](https://docs.getbeekon.com/api/events/) is always there to catch up on anything missed.

## GET `/v1/webhooks`

**Scope:** `webhooks:read` · Lists the project’s webhook endpoints, [paged](https://docs.getbeekon.com/api/pagination/), oldest first.

```sh
curl -s -G https://api.in1.getbeekon.com/v1/webhooks \
  -H "Authorization: Bearer $BEEKON_TOKEN"
```

| Parameter | Required | Meaning                                            |
| --------- | -------- | -------------------------------------------------- |
| `limit`   | no       | 1–500, default 100.                                |
| `cursor`  | no       | The previous page’s `next_cursor` (prefix `wh1_`). |

**Response** `200`: `{"next_cursor": null, "webhooks": [{…}]}`.

## GET `/v1/webhooks/{webhook_id}`

**Scope:** `webhooks:read`

```sh
curl -s \
  https://api.in1.getbeekon.com/v1/webhooks/0199b2d1-3c4d-7e5f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $BEEKON_TOKEN"
```

**Response** `200`: `{"webhook":{…}}`.

## PATCH `/v1/webhooks/{webhook_id}`

**Scope:** `webhooks:write` · Changes any of `endpoint_url`, `event_types` and `status`, in one step. Send at least one.

```sh
curl -s -X PATCH \
  https://api.in1.getbeekon.com/v1/webhooks/0199b2d1-3c4d-7e5f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'
```

| Member         | Rule                                                                                                      |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| `endpoint_url` | As for create. `null` is the same as leaving it out. A `PATCH` without it never re-checks the stored URL. |
| `event_types`  | As for create. **`null` sets “every type”**; leave the member out to keep the current list.               |
| `status`       | `active` or `disabled`. `null` is the same as leaving it out.                                             |

**Response** `200`: `{"webhook":{…}}`.

* `disabled` pauses deliveries: events produced while it is disabled are never sent to it. Events already queued for it wait up to 7 days after they were produced, and are delivered after you set it `active` again. Older ones are given up (**Given up** in the console) and are not sent automatically, even after you set it `active`. Catch up on [`GET /v1/events`](https://docs.getbeekon.com/api/events/).
* After a `PATCH` or `DELETE` returns, deliveries made under the old settings can keep arriving for up to about a minute. Keep verifying signatures and deduplicating on event `id`.

## DELETE `/v1/webhooks/{webhook_id}`

**Scope:** `webhooks:write` · Deletes the endpoint and discards its pending deliveries.

```sh
curl -s -X DELETE \
  https://api.in1.getbeekon.com/v1/webhooks/0199b2d1-3c4d-7e5f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $BEEKON_TOKEN"
```

**Response** `204`, no body. Deleting it again is `404 not found`.

## Rotate the secret

### POST `/v1/webhooks/{webhook_id}/rotate-secret`

**Scope:** `webhooks:write` · Mints a new signing secret and returns it, once.

```sh
WEBHOOK_ID=0199b2d1-3c4d-7e5f-8a9b-0c1d2e3f4a5b
curl -s -X POST \
  "https://api.in1.getbeekon.com/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $BEEKON_TOKEN"
```

The body is optional: send nothing, or `{"expire_previous": true}` (or `false`).

**Response** `200`, with `Cache-Control: no-store`: `{"secret": "whsec_…", "webhook": {…}}`.

| `expire_previous` | What happens to the old secret                                                                                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `false` (default) | It stays valid **until the next rotation**. Deliveries are signed with both the new and the old secret, so a consumer that has not switched yet keeps verifying. |
| `true`            | It is dropped at once. Use this when the old secret has leaked.                                                                                                  |

See [Secret rotation](#secret-rotation) for when your endpoint can stop accepting the old secret.

## Send a test ping

### POST `/v1/webhooks/{webhook_id}/ping`

**Scope:** `webhooks:write` · Sends one signed [`webhook.ping`](https://docs.getbeekon.com/api/events/#ping-events) delivery to the endpoint’s URL, right now, and reports what happened. No request body.

```sh
curl -s -X POST \
  https://api.in1.getbeekon.com/v1/webhooks/0199b2d1-3c4d-7e5f-8a9b-0c1d2e3f4a5b/ping \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  --max-time 30
```

**Response** `200`, whatever your endpoint did: the ping ran, and its outcome is data.

```json
{
  "ping": {
    "delivered": true,
    "delivery_id": "0199b2d4-1b2c-7d3e-8f40-516273849506",
    "status_code": 200
  }
}
```

| Member        | Meaning                                                                                                                                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delivered`   | `true` when your endpoint answered `2xx`.                                                                                                                                                                                       |
| `status_code` | The HTTP status your endpoint answered, or **`null` when it gave no response**: a name that does not resolve, an address Beekon will not call, a refused connection, a TLS failure, a redirect, or no answer within 10 seconds. |
| `delivery_id` | The ping’s `Beekon-Delivery` header, to find it in your logs.                                                                                                                                                                   |

* A ping with no response always takes **10 seconds** to answer, whatever the cause, so the timing tells nobody what is behind the URL. Give your HTTP client a timeout above 10 seconds.
* A ping goes to the endpoint even when it is `disabled`, auto-disabled, or not subscribed to any type, so you can test before you re-enable.
* A ping is signed with every secret the endpoint holds.
* A ping is never retried, never stored, and changes nothing: a successful ping does not lift an auto-disable.
* Pings are limited to 1 a minute per endpoint (bursts of 3) and 20 an hour per project.

## The webhook object

```json
{
  "id": "0199b2d1-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "auto_disabled_at": null,
  "created_at": "2026-10-07T06:30:00.000Z",
  "endpoint_url": "https://hooks.example.com/beekon",
  "event_types": ["geofence.enter", "geofence.exit"],
  "project_id": "019000b0-0000-7000-8000-0000000000b1",
  "status": "active",
  "updated_at": "2026-10-07T06:30:00.000Z"
}
```

All eight members are always present.

| Member                     | Type           | Meaning                                                                                                            |
| -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`                       | string         | The endpoint’s id. Deliveries carry it in `Beekon-Subscription`.                                                   |
| `project_id`               | string         | Your project. Deliveries carry it in `Beekon-Project`.                                                             |
| `endpoint_url`             | string         | Where deliveries go, with the scheme and host lowercased.                                                          |
| `event_types`              | array \| null  | The event types it receives, sorted, without duplicates. **`null` means every type**, including types added later. |
| `status`                   | string         | What you set: `active` or `disabled`.                                                                              |
| `auto_disabled_at`         | string \| null | When Beekon stopped delivering because the endpoint kept failing, or `null`. See [Auto-disable](#auto-disable).    |
| `created_at`, `updated_at` | string         | When it was created and last changed.                                                                              |

The signing secret is **never** part of the object. It is shown once, when you create the endpoint or rotate its secret.

## Endpoint URLs

`endpoint_url` must be a URL Beekon can safely call on the public internet:

* `https://`, at most 2048 bytes, no spaces, control characters or `#fragment`.
* No `user:password@`.
* A public DNS name with at least two labels, such as `hooks.example.com`. Not an IP address, not `localhost`, and not a name under `.local`, `.internal`, `.home.arpa`, `.intranet`, `.lan` or `.corp`.
* Not a Beekon domain (`getbeekon.com`) or a Google serverless default domain (`run.app`, `cloudfunctions.net`, `appspot.com`). Put a custom domain in front of such a service.
* Port 443 or 1024–65535.

Anything else is `400 invalid_endpoint_url`. When Beekon delivers, it also refuses to connect to private, loopback and other non-public addresses, whatever the name resolves to.

## Write-only keys

A key that holds `webhooks:write` but not `webhooks:read` gets a reduced object from every write (create, `PATCH`, rotate): only `{"id":…,"status":…,"updated_at":…}`. The create and rotate responses still include the `secret`.

## Auto-disable

If your endpoint fails persistently (today, after 20 consecutive failed attempts), Beekon stops delivering to it and sets `auto_disabled_at`. Do not depend on the exact threshold or timing.

* `status` still shows what you last set (`active`); `auto_disabled_at` is what tells you deliveries have stopped.
* To resume, fix the endpoint, optionally [ping](#send-a-test-ping) it, then send `PATCH {"status":"active"}`. In fact **any** successful write to the endpoint (`PATCH` of any member, or a rotation) lifts the auto-disable. A ping does not.
* Events already queued for it when it was auto-disabled wait up to 7 days after they were produced, and are delivered once the auto-disable is lifted. Older ones are given up and are not sent automatically.
* Events produced while it was auto-disabled stay readable on [`GET /v1/events`](https://docs.getbeekon.com/api/events/). Reconcile from there.

## Errors

After the session, key-kind and scope checks, the checks run in this order: a server with no webhook service (`503`), then the body’s shape (`400 invalid_body`), then a malformed id (`404`), then the member values (`400 invalid_endpoint_url`, `invalid_event_types`, `invalid_status`), then a busy webhook service (`503`), then an unknown id (`404`), then the rate limits (`429`), and last, on create, the endpoint limit (`409`).

| Status | `error`                                                                             | When                                                                                                                                                                                                                                         |
| ------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_body`                                                                      | Not one JSON object, a body over 16 KiB, an unknown member, a repeated key, a wrong type (an `event_types` element that is not a string included), a `PATCH` with none of the three members, a malformed rotate body, or any body on a ping. |
| 400    | `invalid_endpoint_url`                                                              | `endpoint_url` missing or breaking the [URL rules](#endpoint-urls).                                                                                                                                                                          |
| 400    | `invalid_event_types`                                                               | An empty list, or a type not in the [list of event types](#event-types).                                                                                                                                                                     |
| 400    | `invalid_status`                                                                    | `status` other than `active` or `disabled`.                                                                                                                                                                                                  |
| 400    | `limit must be an integer in [1, 500]` · `invalid_cursor` · `cursor_query_mismatch` | Bad paging on the list.                                                                                                                                                                                                                      |
| 401    | `missing bearer token` · `invalid session token`                                    | No valid session.                                                                                                                                                                                                                            |
| 403    | `server credentials required`                                                       | The token was minted from an SDK key.                                                                                                                                                                                                        |
| 403    | `insufficient scope`                                                                | The key lacks `webhooks:read` (reads) or `webhooks:write` (writes, rotate, ping).                                                                                                                                                            |
| 404    | `not found`                                                                         | Unknown, foreign or malformed id.                                                                                                                                                                                                            |
| 409    | `webhook_limit_reached`                                                             | The project already has 10 endpoints.                                                                                                                                                                                                        |
| 429    | `rate limited`                                                                      | A write or ping limit. Honour `Retry-After`. See [Rate limits](https://docs.getbeekon.com/api/rate-limits/).                                                                                                                                                           |
| 503    | `unavailable, retry`                                                                | The webhook service is briefly busy or unreachable. Retry after `Retry-After` (usually 1 s).                                                                                                                                                 |
| 500    | `internal error`                                                                    | A failure on our side.                                                                                                                                                                                                                       |

Next: the [event types](https://docs.getbeekon.com/api/events/#event-types) your endpoint receives, and [`GET /v1/events`](https://docs.getbeekon.com/api/events/#get-v1events) to catch up on anything it missed.
