API & webhooks

What it's for

API & webhooks is where you build your own integration against Thermal — issue API keys to authenticate requests, and register outbound webhook endpoints so Thermal notifies your system when something happens (currently, a job completing). It's the build-your-own counterpart to Integrations, which connects a first-party service instead of your own code.

Reach it from the API & webhooks tile on Settings → Integrations & data → Integrations, at /settings/integrations/api-webhooks.

Tabs

This screen has no tabs. It's laid out as two side-by-side panels — Outbound webhooks and API keys — with a Docs section and a Recent deliveries log underneath.

Panels and controls

Outbound webhooks

Add endpoint takes a name and a URL and creates an endpoint listening for the job.completed event, enabled by default. Each endpoint row shows its name, an enabled/paused badge, its URL, and the time of its last successful delivery (plus the last error message, if any). Pause/Enable toggles delivery without deleting the endpoint; Delete removes it and its delivery history after a confirmation.

API keys

Create key takes a name and an expiry preset, then shows the full key value exactly once — it's never shown again after this, only its prefix. Each key row shows its name, key prefix, status, last-used time, and expiry (or expired [date] in red once it's passed). An active key can be Rotated — issuing a replacement with a fresh expiry and revoking the old one immediately — or Revoked outright, both behind a confirmation. An expired key stops working immediately; rotating gives you a window to update your integration before the old key's cutover, since the new key is issued at the same moment the old one is revoked.

Docs

Two reference snippets: how to verify a webhook's Thermal-Signature header (HMAC-SHA256 of timestamp + "." + rawBody, using the endpoint's own secret), and a sample authenticated API request using a bearer token.

Recent deliveries

The last dozen webhook delivery attempts across all endpoints — status, event, attempt count, HTTP status code, and error message where relevant. This is a log, not a retry control; there's no manual "redeliver" action here.

What it accepts

Nothing can be saved at all if the platform's encryption for stored credentials isn't configured — "Integration encryption is not configured." Rotating or revoking a key that doesn't belong to this org, or has already been revoked, is refused: "API key not found." / "Only active keys can be rotated."

How to configure it

• Nothing configures this screen from elsewhere — it's the source of truth for keys and endpoints, not a view onto settings held somewhere else.
• What it configures downstream: any client using a Thermal API key authenticates and is authorized exactly per that key's status and expiry; any registered endpoint receives the job.completed webhook the moment it fires, signed with that endpoint's own secret.
• The parent Integrations page is where first-party connected services (QuickBooks, Stripe, Twilio, Postmark) live instead — use this screen only for something you're building yourself.

Who can see it

This screen sits behind the same Integrations area gate as its parent page, which is owner-only — unlike almost every other Settings screen. Office managers, who otherwise have full Settings access, are specifically excluded here; they cannot open this page, issue or rotate a key, or manage a webhook endpoint. Dispatchers and technicians cannot reach it either. The gate is checked on the server, so a direct link does not get around it.

The full role matrix is on Roles & permissions.