Skip to Content
supedocs

Webhooks

Get told when money moves, a budget fills or an agent needs you.

Add a webhook under Settings → Webhooks: a URL and the events to send it. You see its signing secret once.

Events

EventWhen
approval.requestedAn agent asks for a tool, more budget or your Face ID
budget.reachedA budget is used up
balance.lowThe wallet is running low
topup.succeededCredits were added
topup.failedAdding credits failed
workspace.frozenSomeone paused all spending
agent.connectedA new agent signed in
price.changedA tool's price changed
tool.addedA new tool is available
rental.unpaidA rental couldn't be renewed
rental.endedA rental ended

The request

supe sends a POST with a JSON body:

{
  "id": "evt_3f2a9c1d7b6e4a10",
  "type": "budget.reached",
  "workspace": "ws_f40897a04dc54038",
  "created_at": 1794901160.25,
  "title": "…",
  "body": "…",
  "data": {}
}

Headers: X-OEX-Event is the event type, X-OEX-Signature is sha256= followed by the HMAC-SHA256 of the raw body, keyed with your signing secret.

Check the signature

Compute the HMAC over the raw body before you parse it:

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

function isFromSupe(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Send a test event from the webhook's menu on the dashboard to check your endpoint.

On this page