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
| Event | When |
|---|---|
approval.requested | An agent asks for a tool, more budget or your Face ID |
budget.reached | A budget is used up |
balance.low | The wallet is running low |
topup.succeeded | Credits were added |
topup.failed | Adding credits failed |
workspace.frozen | Someone paused all spending |
agent.connected | A new agent signed in |
price.changed | A tool's price changed |
tool.added | A new tool is available |
rental.unpaid | A rental couldn't be renewed |
rental.ended | A 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.