# Receive webhooks (https://orgasm.dev/docs/events/deliverWebhooks)

# Receive webhooks

`send`, channel Webhook delivery: Address: the URL of your webhook endpoint.

orgasm.dev POSTs events to your webhook endpoints.

Register endpoints with `POST /v1/webhook-endpoints`, choosing the event types each receives. Live-session and recording events are delivered alike; `recording.completed` and `recording.failed` exist only here and in the recording's event list, and `credits.low` only here, to live endpoints.

orgasm.dev POSTs one event per request to each enabled endpoint
subscribed to its type, at the URL you registered (so the address is
yours). Requests are signed per the Standard Webhooks specification.

Verify `webhook-signature` before trusting the body: it is `v1,`
followed by the base64 HMAC-SHA256, keyed with the base64 part of your
endpoint's `whsec_` secret, of `{webhook-id}.{webhook-timestamp}.{body}`.
Refuse a `webhook-timestamp` more than five minutes from your clock.

Answer with any 2xx status within 10 seconds. Anything else, or no
answer, is retried with exponential backoff for up to 24 hours. Process
the event after you answer, and deduplicate on `webhook-id`, which is
the event `id`.

## Messages

### `orgasm.onset`: Orgasm onset (webhook)

An orgasm began, delivered to your endpoint.

An orgasm began. Applies to women (the `onset_end` detector). Requires the microphone. The call arrives a few seconds after the moment it names.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `orgasmIndex` (integer, required): Which orgasm of the session this is, from 1. The onset and the end of the same orgasm share it.
- `eventAtS` (number, required): The moment the orgasm began, in stream seconds.
- `calledAtS` (number, required): The moment the detector made the call, in stream seconds.
- `lagS` (number, required): `calledAtS - eventAtS`: how late the call is.
- `detector` (`"onset_end"`, required)
- `score` (number, required): The detector's score for the call, on the scale of `threshold`.
- `threshold` (number, required): The level the detector calls at. A score at or above it made the call.

Example (The onset of a woman’s orgasm, called 4.6 seconds after it began. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_2099smltv0t2c2wzzyzq",
  "object": "event",
  "type": "orgasm.onset",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 969,
  "streamTimeS": 542.6,
  "confidence": "high",
  "data": {
    "orgasmIndex": 1,
    "eventAtS": 538,
    "calledAtS": 542.6,
    "lagS": 4.6,
    "detector": "onset_end",
    "score": 0.71,
    "threshold": 0.5
  },
  "wallTime": "2026-10-16T14:00:55.260Z"
}
```

### `orgasm.peak`: Orgasm peak (webhook)

The peak of an orgasm, delivered to your endpoint.

The peak of an orgasm. Applies to men (the `peak` detector). Requires the microphone. The call arrives a few seconds after the moment it names.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `orgasmIndex` (integer, required): Which orgasm of the session this is, from 1. The peak and the face-based end of the same orgasm share it.
- `eventAtS` (number, required): The moment of the peak, in stream seconds.
- `calledAtS` (number, required): The moment the detector made the call, in stream seconds.
- `lagS` (number, required): `calledAtS - eventAtS`.
- `detector` (`"peak"`, required)
- `score` (number, required)
- `threshold` (number, required)

Example (A man’s peak, called 3.2 seconds after it. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_26m8iv7m9ik1q6bbpxah",
  "object": "event",
  "type": "orgasm.peak",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 1293,
  "streamTimeS": 704.2,
  "confidence": "high",
  "data": {
    "orgasmIndex": 1,
    "eventAtS": 701,
    "calledAtS": 704.2,
    "lagS": 3.2,
    "detector": "peak",
    "score": 0.66,
    "threshold": 0.5
  },
  "wallTime": "2026-10-16T14:01:11.420Z"
}
```

### `orgasm.end`: Orgasm end (webhook)

An orgasm ended, delivered to your endpoint.

An orgasm ended. For women it closes the orgasm an `orgasm.onset` opened (`onset_end`, requires the microphone); for men it follows an `orgasm.peak` and is read from the face (`face_end`).

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `orgasmIndex` (integer, required): Which orgasm of the session ended.
- `eventAtS` (number, required): The moment the orgasm ended, in stream seconds.
- `startedAtS` (number, required): When the same orgasm began: its onset (`onset_end`) or its peak (`face_end`).
- `durationS` (number, required): `eventAtS - startedAtS`.
- `calledAtS` (number, required): The moment the detector made the call, in stream seconds.
- `lagS` (number, required): `calledAtS - eventAtS`.
- `detector` (`onset_end` | `face_end`, required)
- `score` (number | null, required): The detector's score, or `null` for `face_end`, which has none.
- `threshold` (number | null, required): The detector's calling level, or `null` for `face_end`.
- `ruined` (boolean, required): Whether the orgasm was ruined: the last stimulation report before it began was `off`, sent within the 30 seconds before while `p30` was at 0.75 or above (the ruin preset's stop). Charged as a ruin, at the price of an orgasm. Always `false` for a recording, which takes no stimulation reports.

Example (The end of a woman’s orgasm, from the onset-and-end detector. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_2b9vobycwv70h1fs0mre",
  "object": "event",
  "type": "orgasm.end",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 1046,
  "streamTimeS": 580.2,
  "confidence": "high",
  "data": {
    "orgasmIndex": 1,
    "eventAtS": 575,
    "startedAtS": 538,
    "durationS": 37,
    "calledAtS": 580.2,
    "lagS": 5.2,
    "detector": "onset_end",
    "score": 0.68,
    "threshold": 0.5,
    "ruined": false
  },
  "wallTime": "2026-10-16T14:00:59.020Z"
}
```

### `edge.completed`: Edge completed (webhook)

An edge orgasm.dev counted, delivered to your endpoint.

An edge: imminence (`p30`) reached 0.6 and fell back below 0.3 with no orgasm called in between. orgasm.dev counts it on its side, as the edge preset's back-off and resume levels, and charges half a credit for it in live mode. Sent with the reading that completed it; its `confidence` is the lowest of the approach's readings. Without the microphone no orgasm can be called, so every approach that recedes is an edge.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `edgeIndex` (integer, required): Which edge of the session this is, from 1.
- `startedAtS` (number, required): When `p30` reached 0.6, the edge preset's back-off level, in stream seconds.
- `eventAtS` (number, required): When `p30` fell back below 0.3, the preset's resume level, which made the approach an edge, in stream seconds.
- `durationS` (number, required): `eventAtS - startedAtS`.
- `peakP30` (number, required): The highest `p30` of the approach.

Example (The first of three edges: imminence reached 0.6 and fell back below 0.3. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_2gi9on772qb0beswjxgp",
  "object": "event",
  "type": "edge.completed",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 706,
  "streamTimeS": 411,
  "confidence": "high",
  "data": {
    "edgeIndex": 1,
    "startedAtS": 362,
    "eventAtS": 411,
    "durationS": 49,
    "peakP30": 0.687
  },
  "wallTime": "2026-10-16T14:00:42.100Z"
}
```

### `subject.identified`: Subject identified (webhook)

The subject read, delivered to your endpoint.

Once per session or recording, after about 30 seconds of visible face: whether the face reads as a woman's or a man's, and which detectors apply from then on.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `sex` (`woman` | `man` | `undetermined`, required): Whether the face reads as a woman's or a man's, which decides the detectors that apply. `undetermined` is common: the read is made once, from the first 30 seconds of visible face, and only decides when it is clear. It is an estimate for choosing detectors, not a statement about the person's sex or gender identity.
- `pWoman` (number | null, required): The read's probability that the face is a woman's, or `null` when the face could not be read.
- `secondsObserved` (integer, required): Seconds of visible face the read was made from (at most 30).
- `decidedAtS` (number, required): When the read was made, in stream seconds.
- `hint` (`woman` | `man` | `null`, required): The `subjectHint` you gave when you created the session, or `null`.
- `detectors` (array of `onset_end` | `peak` | `face_end`, required): The detectors that apply from now on. A hint decides them when given; otherwise the read does; while undetermined, all of them run and their calls arrive with `confidence: low`.

Example (The face reads as a woman’s. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_0z6tc53e7py0ep61nm8s",
  "object": "event",
  "type": "subject.identified",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 4,
  "streamTimeS": 32,
  "confidence": "high",
  "data": {
    "sex": "woman",
    "pWoman": 0.94,
    "secondsObserved": 30,
    "decidedAtS": 32,
    "hint": null,
    "detectors": [
      "onset_end"
    ]
  },
  "wallTime": "2026-10-16T14:00:04.200Z"
}
```

### `session.status`: Session status (webhook)

A session status change, delivered to your endpoint.

The live session changed status, or its inputs changed.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `status` (`starting` | `ready` | `calibrating` | `analyzing` | `ended`, required): `starting`: analysis capacity is being prepared (a few minutes when none is warm). `ready`: the device can publish. `calibrating`: media is arriving and the person's baseline is being taken. `analyzing`: every signal the inputs allow is running. `ended`: no more events follow.
- `previousStatus` (`starting` | `ready` | `calibrating` | `analyzing` | `ended` | `null`, required)
- `degraded` (boolean, required): An input the session declared is missing, or the face is not visible. The open `input.warning` events say which.
- `inputs` (object, required): Which inputs are arriving right now.
  - `face` (object, required)
  - `audio` (object, required)
  - `body` (object, required)
- `endedReason` (`client_ended` | `media_ended` | `media_timeout` | `max_duration` | `interrupted` | `policy` | `error` | `null`, required): Why the session ended, once `status` is `ended`. `client_ended`: you ended it. `media_ended`: the device stopped publishing. `media_timeout`: no frames arrived for too long. `max_duration`: `maxDurationS` elapsed. `interrupted`: the analysis capacity was lost; create a new session. `policy`: the session broke the acceptable use policy. `error`: an internal failure.

Example (The baseline is in and every signal runs. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_0a8shq12uin1saa234wn",
  "object": "event",
  "type": "session.status",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 5,
  "streamTimeS": 62,
  "confidence": null,
  "data": {
    "status": "analyzing",
    "previousStatus": "calibrating",
    "degraded": false,
    "inputs": {
      "face": {
        "present": true,
        "baselineReady": true
      },
      "audio": {
        "declared": true,
        "present": true
      },
      "body": {
        "declared": false,
        "present": false
      }
    },
    "endedReason": null
  },
  "wallTime": "2026-10-16T14:00:07.200Z"
}
```

### `input.warning`: Input warning (webhook)

An input warning, delivered to your endpoint.

An input problem started (`raised`) or stopped (`cleared`). Show `message` to the person when it helps them fix it.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `code` (`face_not_visible` | `multiple_faces` | `audio_absent` | `baseline_pending` | `body_stream_absent` | `low_confidence`, required): `face_not_visible`: no face is tracked. `multiple_faces`: more than one face is in view and the analysis cannot tell which is the subject. `audio_absent`: the stream carries no microphone, so onset, peak and end are unavailable. `baseline_pending`: imminence starts once the baseline is in. `body_stream_absent`: a declared body view is not arriving. `low_confidence`: input quality is too low for confident calls.
- `state` (`raised` | `cleared`, required): `raised` when the condition starts, `cleared` when it ends.
- `message` (string, required): A sentence you can show the person, in English.
- `sinceS` (number, required): When the condition started, in stream seconds.

Example (The face left the frame. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_1x82ikl67c70dowtacc7",
  "object": "event",
  "type": "input.warning",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 483,
  "streamTimeS": 300,
  "confidence": null,
  "data": {
    "code": "face_not_visible",
    "state": "raised",
    "message": "Your face is not visible. Move back into view of the front camera.",
    "sinceS": 300
  },
  "wallTime": "2026-10-16T14:00:31.000Z"
}
```

### `recording.completed`: Recording completed (webhook)

A recording finished processing.

A recording finished processing. Fetch its events with `listRecordingEvents`.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `durationS` (number, required): Length of the recording, in seconds.
- `orgasmCount` (integer, required): How many orgasms the analysis called in the recording.
- `subject` (object, required)
  - `sex` (`woman` | `man` | `undetermined`, required)
  - `pWoman` (number | null, required)

Example (A 13-minute recording with one orgasm. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_01e7nwowmv01p3y9h7qm",
  "object": "event",
  "type": "recording.completed",
  "mode": "test",
  "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
  "sequence": 722,
  "streamTimeS": 780,
  "confidence": null,
  "data": {
    "durationS": 780,
    "orgasmCount": 1,
    "subject": {
      "sex": "man",
      "pWoman": 0.07
    }
  },
  "wallTime": "2026-10-16T14:00:33.000Z"
}
```

### `recording.failed`: Recording failed (webhook)

A recording could not be processed.

A recording could not be processed.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `code` (`unreadable_media` | `no_face` | `too_short` | `too_long` | `fetch_failed` | `upload_expired` | `internal`, required): `unreadable_media`: the file could not be decoded (H.264 or H.265 video is required). `no_face`: no face was visible long enough to analyse. `too_short`: under two minutes. `too_long`: over four hours. `fetch_failed`: `source.url` could not be fetched. `upload_expired`: the upload URL expired before a file arrived. `internal`: an internal failure; submit it again.
- `message` (string, required)

Example (The enclave could not fetch source.url. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_7r2k9m4x1c6v8b3n5q0z",
  "object": "event",
  "type": "recording.failed",
  "mode": "test",
  "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
  "sequence": 1,
  "streamTimeS": 0,
  "confidence": null,
  "data": {
    "code": "fetch_failed",
    "message": "source.url answered 403 Forbidden."
  },
  "wallTime": "2026-10-16T14:00:33.000Z"
}
```

### `credits.low`: Credits low (webhook)

Your company's credits fell to 20% of its latest package, delivered to your live endpoints.

Your company's credit balance fell to 20% or less of its latest package (4 of the free 20). Sent once per package, by webhook only, to the company's live endpoints subscribed to it. It belongs to no session, so it has no `sessionId`, `sequence` or stream time.

Headers:

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)

Fields of `data`:

- `domain` (string, required): The company domain the credits belong to.
- `balance` (number, required): Credits available now, in halves.
- `threshold` (number, required): The level that sent it: 20% of the credits the latest package posted (4 of the free 20).
- `freeRemaining` (number, required): How many of the free credits are left.
- `packageId` (string, required): The package the threshold is measured against.

Example (Four of the free 20 left. Signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.):

```json
{
  "id": "evt_5c2x8v1b4n7m0q3w6e9r",
  "object": "event",
  "type": "credits.low",
  "mode": "live",
  "wallTime": "2026-10-16T14:21:07Z",
  "data": {
    "domain": "studio.example",
    "balance": 4,
    "threshold": 4,
    "freeRemaining": 4,
    "packageId": "free"
  }
}
```