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 → Data and connections → 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 Zapier, external agent clients, Webhook integrations, a Docs section, a Recent deliveries log, and Failed deliveries 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.

Zapier

Shows Zapier not connected until you connect a Zap. Connect Zapier takes a Zap name and a Catch Hook URL (https://hooks.zapier.com/hooks/catch/…, without a port or credentials). On success it shows "Zapier connected — copy the signing secret now"; the secret is shown once. Revoke disconnects the Zap after a confirmation, and it stops receiving completed jobs.

Webhook integrations

Webhook integrations holds credentials for incoming partner webhooks. Integration name is required, up to 80 characters. Create integration issues the credential. An owner without a linked staff record gets "Your staff record must be linked before creating an integration." The page then says Copy the signing secret now — it is shown only once, with the integration id and the secret. With none yet, the section says No webhook integrations. Columns are Name, Integration ID, Status (enabled, paused, or revoked), Last used, and Actions. Revoke disables that credential after you confirm. An enabled integration that is not revoked also has Rotate secret. Confirm Rotate signing secret? The current secret keeps working for one hour. If you already rotated, that older secret stops immediately. The page then shows New signing secret and says Copy it now — shown only once. The previous secret works for one hour. A missing staff link says "Your staff record must be linked before rotating an integration." A disabled or missing integration says "This integration is unavailable or disabled." Outbound job notifications stay on Outbound webhooks. A company with no rows here has not connected a partner yet. Saving still requires the platform encryption named below.

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 log does not retry a delivery.

Failed deliveries

Failed deliveries lists up to 100 failed attempts, newest first. Columns are Event, Endpoint, Attempts, Last error, Created, and Replay. Replay sends that same event to the same endpoint, with up to three attempts, and keeps its deduplication key. The button reads Queuing… while it works, then Queued for delivery. A paused endpoint disables Replay and says Endpoint paused. Resume it to replay. If the delivery cannot be queued, the page says Only failed deliveries on enabled endpoints can be replayed. Resume a paused endpoint first; this delivery may already be queued. With nothing failed, the section says No failed deliveries.

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, Telnyx, 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.