# Create a webhook endpoint (https://orgasm.dev/docs/api/webhooks/createWebhookEndpoint)

# Create a webhook endpoint

- **Method:** `POST`
- **Path:** `/v1/webhook-endpoints`
- **Operation ID:** `createWebhookEndpoint`
- **Tags:** webhooks

Registers an HTTPS URL on your server to receive events as POSTs,
signed per the Standard Webhooks specification (`webhook-id`,
`webhook-timestamp`, `webhook-signature`). The response carries the
signing `secret` once; store it.

Every event type except `imminence.updated`, `signals.updated` and
`stimulation.updated` can be delivered; those arrive often and are
only streamed.
Deliveries are at least once: deduplicate on the event `id`.

Next: call `sendTestWebhook` to check your receiver verifies the
signature.

## Effective servers

- `https://orgasm.dev`

  `sk_test_` keys reach the sandbox. `sk_live_` keys are refused until live analysis is available.
- `http://localhost:3000`

  The docs site running locally (`npm run dev`), which serves the sandbox.
- `http://localhost:4010`

  The standalone sandbox (`npm run mock`), which also serves the WebSocket channel.

## Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  A secret key, sent as `Authorization: Bearer sk_test_…`. Keep it on your server. Test keys reach the sandbox; live keys reach live analysis. In the sandbox any key that starts with `sk_test_` works.

## Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  A unique value, such as a UUID, that makes retrying this request safe: a retry with the same key and body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of acting twice. The same key with a different body is refused with `idempotency_key_reused`.

## Request body

The URL and the event types to deliver.

**Required:** `true`

**Content type:** `application/json`

schema: `WebhookEndpointCreateRequest`

Where to deliver events, and which.

- **`events` (required)**: `array`, minItems: `1`, uniqueItems: `true`

  The event types to deliver.

  **Items:**

  `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed", "credits.low"`

  Every event type except `imminence.updated`, `signals.updated` and `stimulation.updated`, which are only streamed, and `credits.low`, your company's balance, which only webhooks carry (to live endpoints).
- **`url` (required)**: `string`, format: `uri`, pattern: `^(https://|http://localhost(:[0-9]+)?/|http://127\.0\.0\.1(:[0-9]+)?/)`

  An HTTPS URL on your server. In test mode `http://localhost` and `http://127.0.0.1` are accepted too, for local development.
- **`description`**: `string`, maxLength: `500`
- **`enabled`**: `boolean`, default: `true`

**Example: orgasmEvents**

Orgasm calls and session status

```json
{
  "url": "https://api.example.com/hooks/orgasm-dev",
  "events": [
    "orgasm.onset",
    "orgasm.peak",
    "orgasm.end",
    "subject.identified",
    "session.status"
  ],
  "description": "Production receiver"
}
```

## Responses

### 201 The endpoint, with its signing secret.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

schema: `WebhookEndpoint`

A URL on your server that receives events.

- **`createdAt` (required)**: `string`, format: `date-time`
- **`description` (required)**: `string | null`
- **`enabled` (required)**: `boolean`
- **`events` (required)**: `array`

  **Items:**

  `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed", "credits.low"`

  Every event type except `imminence.updated`, `signals.updated` and `stimulation.updated`, which are only streamed, and `credits.low`, your company's balance, which only webhooks carry (to live endpoints).
- **`id` (required)**: `string`, pattern: `^we_[0-9a-z]{20}$`
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"webhook_endpoint"`
- **`previousSecretExpiresAt` (required)**: `string | null`, format: `date-time`

  After `rollWebhookSecret`, until when deliveries are also signed with the previous secret; `null` otherwise.
- **`secret` (required)**: `string | null`

  The signing secret (`whsec_` and base64), only in the response that created the endpoint or rolled its secret; `null` afterwards.
- **`url` (required)**: `string`, format: `uri`

**Example: created**

A new endpoint and its secret

Returned by createWebhookEndpoint.

```json
{
  "id": "we_5h8j1k4l7z0x3c6v9b2n",
  "object": "webhook_endpoint",
  "mode": "test",
  "url": "https://api.example.com/hooks/orgasm-dev",
  "events": [
    "orgasm.onset",
    "orgasm.peak",
    "orgasm.end",
    "subject.identified",
    "session.status"
  ],
  "description": "Production receiver",
  "enabled": true,
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
  "previousSecretExpiresAt": null,
  "createdAt": "2026-10-16T14:00:00Z"
}
```

### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

schema: `Problem`

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

- **`code` (required)**: `string`, possible values: `"invalid_request", "consent_required", "capability_required", "sandbox_only", "authentication_required", "invalid_api_key", "live_mode_unavailable", "credits_exhausted", "permission_denied", "not_found", "idempotency_key_reused", "session_ended", "sandbox_no_media", "upload_already_received", "payload_too_large", "rate_limited", "capacity_unavailable", "internal_error"`

  A stable, machine-readable error code.
- **`status` (required)**: `integer`

  The HTTP status code.
- **`title` (required)**: `string`

  A short summary of the error.
- **`type` (required)**: `string`, format: `uri`

  A link to the docs for this error.
- **`detail`**: `string`

  What went wrong in this request, and what to do.
- **`errors`**: `array`

  Each contract violation, when the body or a parameter did not match the contract.

  **Items:**
  - **`location` (required)**: `string`, possible values: `"path", "query", "header", "cookie", "body"`
  - **`message` (required)**: `string`
  - **`path` (required)**: `string`

    JSON pointer to the value at fault.
- **`instance`**: `string`

  The request path.
- **`param`**: `string | null`

  The request field at fault, as a dotted path, when there is one.
- **`requestId`**: `string`

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#invalid_request",
  "title": "The request is invalid",
  "status": 400,
  "code": "invalid_request",
  "detail": "limit must be <= 100",
  "param": "limit",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#invalid_api_key",
  "title": "The API key is not valid",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "Send a secret key as `Authorization: Bearer sk_test_…`. In the sandbox any key that starts with sk_test_ works.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#live_mode_unavailable",
  "title": "Live analysis is not available yet",
  "status": 403,
  "code": "live_mode_unavailable",
  "detail": "Live keys are not accepted yet. Use a key that starts with sk_test_ to reach the sandbox.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 409 The request conflicts with the resource's state, or an idempotency key was reused.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#session_ended",
  "title": "The session has ended",
  "status": 409,
  "code": "session_ended",
  "detail": "ls_8f3kq2m7x9w4c1n6t5ra ended at 2026-10-16T14:12:00Z.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#consent_required",
  "title": "Consent is required",
  "status": 422,
  "code": "consent_required",
  "detail": "consent.subjectIsAdult and consent.subjectConsented must both be true.",
  "param": "consent",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

*Schema `Problem` is shown above.*

**Example:**

```json
{
  "type": "https://orgasm.dev/docs/guides/errors#rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "Retry after 2 seconds.",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

## Schemas

- `Problem` — shown above.

### ErrorCode

**Type:** `string`, possible values: `"invalid_request", "consent_required", "capability_required", "sandbox_only", "authentication_required", "invalid_api_key", "live_mode_unavailable", "credits_exhausted", "permission_denied", "not_found", "idempotency_key_reused", "session_ended", "sandbox_no_media", "upload_already_received", "payload_too_large", "rate_limited", "capacity_unavailable", "internal_error"`

A stable, machine-readable error code.

### WebhookEventType

**Type:** `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed", "credits.low"`

Every event type except `imminence.updated`, `signals.updated` and `stimulation.updated`, which are only streamed, and `credits.low`, your company's balance, which only webhooks carry (to live endpoints).

- `WebhookEndpointCreateRequest` — shown above.
- `WebhookEndpoint` — shown above.
