orgasm.dev

Webhooks

Receive events as signed POSTs, verify them, and handle retries and duplicates.

A webhook endpoint is a URL on your server that receives events as HTTP POSTs, signed per the Standard Webhooks specification. Every event type can be delivered except imminence.updated, signals.updated and stimulation.updated, which arrive often and are only streamed. One more type exists only here: credits.low, sent to live endpoints when your company's balance runs low (Credits and billing).

Register an endpoint

curl -s https://orgasm.dev/v1/webhook-endpoints \
  -H "Authorization: Bearer $ORGASM_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://api.example.com/hooks/orgasm-dev",
        "events": ["orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "recording.completed", "credits.low"] }'

The response carries the endpoint's signing secret (whsec_…) once. Store it. By default every session and recording delivers to every endpoint subscribed to an event's type; set webhookEndpointId on a session or recording to deliver its events to one endpoint only.

Verify every delivery

Each POST carries three headers:

HeaderValue
webhook-idThe event id; the same on every retry
webhook-timestampWhen this attempt was sent, in Unix seconds
webhook-signaturev1, and the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}

Verify before you trust the body, against the raw body as received:

verify.ts
export async function verify(secret: string, headers: Headers, body: string, nowS = Date.now() / 1000): Promise<boolean> {
  const id = headers.get('webhook-id');
  const timestamp = headers.get('webhook-timestamp');
  const signatures = headers.get('webhook-signature');
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(nowS - Number(timestamp)) > 300) return false;
  const key = await crypto.subtle.importKey(
    'raw',
    Uint8Array.from(atob(secret.replace(/^whsec_/, '')), (c) => c.charCodeAt(0)),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign'],
  );
  const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${id}.${timestamp}.${body}`));
  const expected = `v1,${btoa(String.fromCharCode(...new Uint8Array(mac)))}`;
  return signatures.split(' ').includes(expected);
}

Any Standard Webhooks library verifies the same headers. The examples in the events reference are signed with the sample secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw, so you can test your verifier against them: pass the example's webhook-timestamp as nowS.

Answer fast, process later

Answer with any 2xx within 10 seconds, then process. Any other answer, or none, is retried with exponential backoff for up to 24 hours.

  • Deliveries are at least once: deduplicate on webhook-id.
  • Retries arrive out of order: sort by sequence within a session or recording. credits.low has no sequence; order it by wallTime.

Test your receiver

sendTestWebhook sends one signed sample event of the type you choose and reports how your server answered: status code, duration and the headers it sent. In test mode, http://localhost and http://127.0.0.1 URLs are accepted, so you can point an endpoint at a server on your machine.

On this page