Webhooks
Receive TestRelic Console events (top-ups, spend alerts, key and member changes, MCP tool changes) at your own HTTPS endpoint, and verify the Ostra-Signature header.
Webhooks send workspace events to your endpoint as they happen: billing, API keys, members and MCP tools. Set them up in the Console under Settings → Webhooks (owners and admins).
Events
| Event | Group | Sent when |
|---|---|---|
billing.topup | Billing | A top-up payment succeeded. |
billing.auto_topup | Billing | An auto top-up charged the saved card. |
billing.auto_topup_failed | Billing | An auto top-up charge failed. Three failures in a row turn auto top-up off. |
billing.coupon_redeemed | Billing | A coupon code added credit. |
billing.spend_alert | Billing | This month’s spend crossed the alert percentage of the monthly spend limit (once a month). |
api_key.created | API keys | A key was created. |
api_key.revoked | API keys | A key was revoked. |
member.joined | Members | Someone joined the workspace. |
member.removed | Members | A member was removed. |
member.role_changed | Members | A member’s role changed. |
mcp.tool_enabled | MCP | An MCP tool was turned on. |
mcp.tool_disabled | MCP | An MCP tool was turned off. |
webhook.test | Test | You clicked Send test event. |
New endpoints start subscribed to billing.topup, billing.spend_alert, api_key.created and api_key.revoked; pick any events you need.
Delivery
Each event is a POST with a JSON body:
{
"id": "evt_01JDXKC4D5E6F7G8H9J0K1L2M3",
"type": "api_key.created",
"created_at": "2026-11-20T09:14:03.512Z",
"workspace": { "id": "org_01JD…", "name": "Acme QA" },
"data": { "actor": "dana@acme.dev", "detail": "github-actions-web (full, ostk_live_…a91F)" }
}| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Ostra-Webhooks/1.0 (+https://console.testrelic.ai) |
Ostra-Event | The event type, e.g. api_key.created |
Ostra-Delivery | The event id (evt_…), the same as id in the body |
Ostra-Signature | t=<unix seconds>,v1=<hex signature>, see below |
Rules:
- Your endpoint must be public HTTPS. Private, loopback and link-local addresses are refused, and so are URLs with credentials in them.
- Answer with any 2xx within 3 seconds. Do slow work after responding.
- Redirects aren't followed, and failed deliveries aren't retried. After 3 failures in a row the endpoint shows as Failing in the Console; its details list the last 10 deliveries.
- Events can arrive out of order. Use
created_atto order them andidto drop duplicates. - Up to 10 endpoints per workspace. Send test event sends a
webhook.testevent.
Verifying signatures
Every delivery is signed with your endpoint's signing secret (whsec_…), shown once when you create the endpoint (rotate it from the endpoint's menu). The signature is:
v1 = hex( HMAC-SHA256( key = signing secret (the whole string, including "whsec_"),
message = "<t>.<raw request body>" ) )To verify: split the header on , into t and v1, reject t more than 5 minutes from now, compute the HMAC over the raw body bytes exactly as received (before any JSON parsing), and compare in constant time.
import { createHmac, timingSafeEqual } from 'node:crypto';
// header: the Ostra-Signature value; body: the raw request body as a string.
export function verifyOstra(header: string, body: string, secret: string, toleranceSec = 300): boolean {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest();
const got = Buffer.from(parts.v1 ?? '', 'hex');
return got.length === expected.length && timingSafeEqual(got, expected);
}
// Express: keep the raw body for this route.
// app.post('/ostra/webhooks', express.text({ type: 'application/json' }), (req, res) => {
// if (!verifyOstra(req.get('ostra-signature') ?? '', req.body, process.env.OSTRA_WEBHOOK_SECRET!)) return res.sendStatus(400);
// const event = JSON.parse(req.body);
// res.sendStatus(200);
// });Store the signing secret like an API key (environment variable or secrets manager). If it leaks, rotate it in the Console; the old secret stops working immediately.
Agent prompt
Paste this into your coding agent: "Add an HTTPS endpoint at /ostra/webhooks that verifies the Ostra-Signature header (format t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>, secret from OSTRA_WEBHOOK_SECRET, 5-minute tolerance, constant-time compare, raw body before JSON parsing), returns 400 on failure and 200 within 3 seconds on success, de-duplicates by the body's id, and handles billing.spend_alert and api_key.revoked by posting to our team chat. Add tests with a known signature."