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:
| Header | Value |
|---|---|
webhook-id | The event id; the same on every retry |
webhook-timestamp | When this attempt was sent, in Unix seconds |
webhook-signature | v1, and the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body} |
Verify before you trust the body, against the raw body as received:
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
sequencewithin a session or recording.credits.lowhas nosequence; order it bywallTime.
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.
Show the HUD
A heads-up display of the session for your users, as a siderail, a bottom bar, a card in a game or the whole panel with the face and the timeline, or drawn natively from the same model.
Verify the enclave
Read the enclave's source, check a release's SLSA provenance and signature, and check that the machine a live session runs on is that release, without taking orgasm.dev's word for any of it.