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

EventGroupSent when
billing.topupBillingA top-up payment succeeded.
billing.auto_topupBillingAn auto top-up charged the saved card.
billing.auto_topup_failedBillingAn auto top-up charge failed. Three failures in a row turn auto top-up off.
billing.coupon_redeemedBillingA coupon code added credit.
billing.spend_alertBillingThis month’s spend crossed the alert percentage of the monthly spend limit (once a month).
api_key.createdAPI keysA key was created.
api_key.revokedAPI keysA key was revoked.
member.joinedMembersSomeone joined the workspace.
member.removedMembersA member was removed.
member.role_changedMembersA member’s role changed.
mcp.tool_enabledMCPAn MCP tool was turned on.
mcp.tool_disabledMCPAn MCP tool was turned off.
webhook.testTestYou 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)" }
}
HeaderValue
Content-Typeapplication/json
User-AgentOstra-Webhooks/1.0 (+https://console.testrelic.ai)
Ostra-EventThe event type, e.g. api_key.created
Ostra-DeliveryThe event id (evt_…), the same as id in the body
Ostra-Signaturet=<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_at to order them and id to drop duplicates.
  • Up to 10 endpoints per workspace. Send test event sends a webhook.test event.

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."

Was this page helpful?

On this page