Team & Settings

Webhooks

Webhooks push events from Routebase to your own services as HTTP POST requests, so you can wire Routebase into your CI/CD pipeline, a chat channel, or any external tool. When something you've subscribed to happens — a spec is published, a test run fails, a member joins — Routebase delivers a signed JSON payload to a URL you control.

Webhooks are managed per organization under Settings → Webhooks (in the Automation & Integrations group).

Webhooks are a Starter plan feature and require the notifications:manage permission (Admins and Owners by default). On the Free plan the page shows an upgrade card with a View Plans button instead of the webhook manager. The number of webhooks you can create is also plan-limited — see the Usage panel in Billing.

Sending alerts to Slack or Microsoft Teams? Use Settings → Messaging instead. It creates the same webhooks under the hood, but formats the messages for the chat client and lets you pick alert categories instead of raw event types. Slack connects in one click with Add to Slack; if your workspace blocks third-party apps, Connect manually still accepts an incoming webhook URL. Channels connected there are managed on the Messaging page and do not appear in the list below.

Creating a webhook

  1. Open Settings → Webhooks and click Create Webhook.
  2. Fill in the dialog and click Create Webhook.
  3. Copy the signing secret shown in the Webhook Secret dialog — "Make sure to copy the secret below — you won't be able to see it again!"
The Create Webhook dialog with name, payload URL, event selection and max retries
Field Notes
Name Required. A label you'll recognize in the list, e.g. "CI/CD Pipeline Webhook".
Description Optional context.
Payload URL Required. The endpoint that receives the POST. Must use HTTP or HTTPS — HTTPS is recommended.
Events Required. One or more event types to subscribe to (see below).
Max Retries How many times a failed delivery is retried: No retries, 1, 2, 3 (default), 5, or 10.
Enabled Shown when creating only — whether the webhook starts receiving events right away.

Event types

Events are grouped by area. Most subscriptions use a wildcard that covers the whole group; Testing additionally offers two specific events:

Group Event Fires when
API Design spec.* A spec is published or deprecated, or breaking changes land
endpoint.* An endpoint is created, updated, or deleted
schema.* A schema is created, updated, or deleted
version.* A version is created or its status changes
Testing test_run.* A test run completes, passes, fails, or errors
test_run.failed One or more assertions fail
test_run.passed All assertions pass
Projects project.* A project is created or archived, or its members change
Mock Server mock_server.* A mock server is enabled, disabled, or its config changes
Style Guide style_guide.* Violations are found or a publish is blocked
Team team.* A member is invited or removed, or a role changes

The payload and verifying it

Each delivery is a JSON POST to your Payload URL:

{
  "eventType": "test_run.failed",
  "timestamp": "2026-01-15T09:24:00Z",
  "organizationId": null,
  "projectId": null,
  "actorUserName": "Jane Doe",
  "data": {
    "testSuiteName": "Smoke Tests",
    "passedCases": 11,
    "failedCases": 2
  }
}

The data object carries the event-specific fields; its exact shape depends on the event type.

Every request includes three headers:

Header Contains
X-Routebase-Signature sha256= followed by an HMAC-SHA256 signature (hex, lowercase) of the raw request body, computed with your webhook's signing secret
X-Routebase-Event The event type of this delivery
X-Routebase-Delivery A unique ID for this delivery

To verify a delivery, recompute the HMAC-SHA256 of the raw body with your secret and compare it to the value after sha256= in the signature header. A match confirms the request genuinely came from Routebase and wasn't tampered with in transit.

The signing secret

The secret is shown once — when the webhook is created and whenever you regenerate it. Choose Regenerate Secret from a webhook's menu to issue a fresh one; the previous secret stops working immediately, so update your receiver to match.

Managing webhooks

Each webhook appears as a card showing its name, an Active or Inactive badge, the target URL, the events it's subscribed to, and its description. The card's menu offers:

A webhook card with its actions menu open
  • Edit — change the name, description, URL, events, or max retries.
  • Send Test — fire a sample delivery (event type test) at your URL so you can confirm your receiver works. Only available while the webhook is enabled.
  • Delivery History — review past deliveries (see below).
  • Enable / Disable — pause a webhook without deleting it; a disabled webhook keeps its configuration but stops receiving events.
  • Regenerate Secret — issue a fresh signing secret (shown once).
  • Delete — remove the webhook permanently after confirming. Any pending deliveries are cancelled.

Delivery history and retries

Delivery History opens a paginated table (20 per page) of recent deliveries:

Column Shows
Event The event type that triggered the delivery
Status Delivered, Failed, Retrying, or Pending
HTTP The HTTP status code your endpoint returned
Attempts How many times Routebase tried to deliver
Timestamp When the delivery occurred

A delivery counts as successful when your endpoint returns a 2xx status. Anything else is retried with exponential backoff — 1 minute after the first failure, then 2, 4, 8 minutes and so on — up to the Max Retries you configured, after which the delivery is marked Failed.

The delivery history is the first place to look when an integration isn't reacting to events: check whether deliveries reach your endpoint and what status code it sent back.