Quickstart

read -rs SESS_API_KEY && export SESS_API_KEY   # paste the key, then press Enter

curl -sS -X POST "$SESS_API/v1/sessions" \
  -H "Authorization: Bearer $SESS_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @review.json \
  -o session.json -w '%{http_code}\n'
export SESSION_ID="$(jq -r .id session.json)"
jq -r .human_url session.json   # send this link to the person

curl -sS -D headers.txt -o current.json \
  "$SESS_API/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SESS_API_KEY"
jq '{status, revision, result: .responses[-1].data}' current.json
export ETAG="$(grep -i '^etag:' headers.txt | cut -d' ' -f2- | tr -d '\r')"

cat > round2.json <<'JSON'
{
  "interaction": {
    "mode": "interactive",
    "title": "Confirm the approved invoices",
    "description": "Synthetic data. INV-1 and INV-3 are approved; INV-3 was corrected to 909.",
    "source": {
      "kind": "sess_surface",
      "components": [
        { "type": "record", "label": "INV-1", "fields": { "id": "INV-1", "vendor": "Acme", "amount": 120 } },
        { "type": "record", "label": "INV-3", "fields": { "id": "INV-3", "vendor": "Initech", "amount": 909 } },
        {
          "type": "field",
          "name": "payment_note",
          "label": "Note for the payment run",
          "schema": { "type": "string", "maxLength": 200 }
        }
      ]
    },
    "actions": [
      { "id": "confirm", "label": "Confirm", "intent": "approve" },
      { "id": "change", "label": "Request a change", "intent": "request_change" }
    ]
  }
}
JSON

curl -sS -X PATCH "$SESS_API/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SESS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" \
  -H "Idempotency-Key: round-2-$SESSION_ID" \
  --data-binary @round2.json \
  -o current.json -w '%{http_code}\n'

{ "payment_note": "Pay both in the next run." }

cat > round3.json <<'JSON'
{
  "interaction": {
    "mode": "interactive",
    "title": "Choose the payment date",
    "description": "Synthetic data. Two approved invoices, 1,029 in total.",
    "source": {
      "kind": "sess_surface",
      "components": [
        { "type": "text", "text": "Pick the run in which INV-1 and INV-3 are paid." },
        {
          "type": "field",
          "name": "pay_on",
          "label": "Payment run",
          "required": true,
          "schema": { "type": "string", "enum": ["2026-11-02", "2026-11-09"] },
          "option_labels": { "2026-11-02": "Monday 2 November", "2026-11-09": "Monday 9 November" }
        }
      ]
    },
    "actions": [{ "id": "schedule", "label": "Schedule payment", "intent": "submit" }]
  }
}
JSON

{ "pay_on": "2026-11-09" }

curl -sS -X POST "$SESS_API/v1/sessions/$SESSION_ID/complete" \
  -H "Authorization: Bearer $SESS_API_KEY" \
  -H "If-Match: $ETAG" \
  -o current.json -w '%{http_code}\n'
jq .status current.json

curl -sS "$SESS_API/v1/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $SESS_API_KEY" \
  | jq -c '.events[] | {sequence, type, revision, action_id} | with_entries(select(.value != null))'

{"sequence":1,"type":"response.accepted","revision":1,"action_id":"submit"}
{"sequence":2,"type":"revision.published","revision":2}
{"sequence":3,"type":"response.accepted","revision":2,"action_id":"confirm"}
{"sequence":4,"type":"revision.published","revision":3}
{"sequence":5,"type":"response.accepted","revision":3,"action_id":"schedule"}
{"sequence":6,"type":"session.completed","revision":3}

import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';

// whsec_… secrets in force: add the new one when you rotate, remove the old one after retire_at.
const secrets = [process.env.SESS_WEBHOOK_SECRET].filter(Boolean);
if (secrets.length === 0) throw new Error('Set SESS_WEBHOOK_SECRET to your whsec_… signing secret');
const seen = new Set(); // use your database in production

function verified(id, ts, body, header) {
  if (!id || !(Math.abs(Date.now() / 1000 - Number(ts)) < 300)) return false;
  const signatures = String(header ?? '').split(' ').map((s) => s.slice(3)); // drop "v1,"
  return secrets.some((secret) => {
    const mac = createHmac('sha256', Buffer.from(secret.slice(6), 'base64')) // drop "whsec_"
      .update(`${id}.${ts}.${body}`)
      .digest();
    return signatures.some((s) => {
      const given = Buffer.from(s, 'base64');
      return given.length === mac.length && timingSafeEqual(given, mac);
    });
  });
}

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const body = Buffer.concat(chunks).toString('utf8'); // the exact bytes that were signed
    const id = req.headers['webhook-id'];
    const ts = req.headers['webhook-timestamp'];
    if (!verified(id, ts, body, req.headers['webhook-signature'])) return res.writeHead(401).end();
    const msg = JSON.parse(body);
    if (msg.type === 'sess.webhook.verification') {
      res.writeHead(200, { 'content-type': 'application/json' });
      return res.end(JSON.stringify({ challenge: msg.challenge }));
    }
    if (!seen.has(id)) {
      seen.add(id);
      console.log(msg.session_id, msg.revision, msg.action_id, msg.data); // msg.receipt: the signed receipt
    }
    res.writeHead(200).end();
  });
}).listen(8443); // behind your HTTPS terminator, e.g. https://hooks.example.com/sess

cat > hook.json <<'JSON'
{ "url": "https://hooks.example.com/sess" }
JSON

curl -sS -X PUT "$SESS_API/v1/webhook" \
  -H "Authorization: Bearer $SESS_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @hook.json \
  -o webhook.json -w '%{http_code}\n'
jq '.endpoint | {id, status}' webhook.json

curl -sS -X POST "$SESS_API/v1/webhook/verify" \
  -H "Authorization: Bearer $SESS_API_KEY" -w '\n%{http_code}\n'

{
  "type": "response.accepted",
  "event_id": "evt_01JABCDEFGHJKMNPQRSTVWXYZ1",
  "session_id": "ses_01JABCDEFGHJKMNPQRSTVWXYZ0",
  "sequence": 1,
  "revision": 1,
  "action_id": "submit",
  "data": { "inv_3_amount": 909, "approved": ["INV-1", "INV-3"] },
  "accepted_at": "2026-01-01T00:00:00.000Z",
  "receipt": "{the signed decision receipt}"
}

curl -sS "$SESS_API/v1/sessions/$SESSION_ID/deliveries" \
  -H "Authorization: Bearer $SESS_API_KEY" | jq '.deliveries[] | {event_id, status, last_outcome}'

export EVENT_ID="evt_01JABCDEFGHJKMNPQRSTVWXYZ1"   # an event_id from the log or the Events list
curl -sS -X POST "$SESS_API/v1/sessions/$SESSION_ID/events/$EVENT_ID/redeliver" \
  -H "Authorization: Bearer $SESS_API_KEY" -w '\n%{http_code}\n'

curl -sS -X POST "$SESS_API/v1/webhook/secrets/rotate" \
  -H "Authorization: Bearer $SESS_API_KEY" -o rotated.json -w '%{http_code}\n'

curl -sS "$SESS_API/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SESS_API_KEY" -w '\n%{http_code}\n'