Webhooks

Webhooks allow you to listen to triggers from Schematic to create alerts or keep external services up to date when data changes.

Supported webhook events

The table below lists every supported event and links to its payload type in the Node.js SDK. See Payload types below for links to other SDKs.

Company & User events

Catalog events

Billing events

For usage-based trigger events, see Entitlement & Credit Trigger Webhooks.

Payload types

All webhook event payloads are strongly typed in each of our SDKs. The Node.js types are linked in the table above. The same type names are available in Go, C#, Java, and Python.

Webhook structure

Each webhook from Schematic is a POST request with a JSON body structured as follows.

{
  "action": "<webhook.name>",
  "account_id": "acct_xxxxxxx",
  "environment_id": "env_xxxxxxxx",
  "event_id": "whe_xxxxxxxx",
  "object_type": "<object>",
  "body": {},
  // if applicable
  "company_id": "comp_xxxxxxxx",
  "feature_id": "feat_xxxxxxxx"
}

The contents of body vary depending on the event. You can inspect real payloads using free services like Webhook.site or the webhook log in the Schematic dashboard.

Signature verification

Every webhook request Schematic sends includes three headers for verifying authenticity:

The signature is computed as:

HMAC-SHA256(secret, rawBody + "+" + timestamp)  →  hex-encoded

where secret is the webhook secret shown in the Schematic dashboard when you create the webhook endpoint.

Each SDK ships a built-in helper to handle verification for you:

import { verifyWebhookSignature } from "@schematichq/schematic-typescript-node";
// Express example
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    verifyWebhookSignature(req, process.env.SCHEMATIC_WEBHOOK_SECRET, req.body);
  } catch (err) {
    return res.status(400).send("Invalid signature");
  }
  const event = JSON.parse(req.body.toString());
  // handle event...
  res.sendStatus(200);
});

Delivery and retries

Schematic delivers webhooks asynchronously. Your endpoint should acknowledge receipt by responding with any 2xx status code.

If your endpoint responds with a non-2xx status (anything 300 or above) or the request times out, Schematic treats the delivery as failed and retries it. You get eight attempts spread across roughly 24 hours, so you can take an endpoint down for a deploy, or sleep through an outage, and still receive the event. Each attempt lands at the offset below from the first attempt, jittered by ±10% so a shared outage does not replay every event at the same instant.

Once the eighth attempt fails, Schematic does not deliver the event again. Disabling or deleting the endpoint also stops any retries still in flight for it, and re-enabling the endpoint does not resume them.

Deduplicating deliveries

You can receive the same event twice, most often when your endpoint processes a request but its response is lost in transit and Schematic retries. Every attempt at one event for one endpoint carries the same event_id in the body and in the X-Schematic-Webhook-Id header, so record the ids you have handled and drop a repeat rather than running your handler again.

Endpoint health

If an endpoint fails consistently, Schematic automatically deactivates it so it stops sending to a broken destination. Our threshold for deactivation is a failure rate of 90% or higher across at least 25 events in a rolling 24-hour window. A delivery counts toward that rate once it has failed three attempts, roughly half an hour in, so Schematic catches a broken endpoint without waiting out every event’s full retry window. You can re-enable the endpoint from the webhooks page in the dashboard once the issue is resolved.

Developer Tooling

On the webhooks page in Schematic, you can find a log of all webhooks Schematic has sent for your account. We will only show events that have an associated webhook configured.

Each event gets one row per endpoint, and that row is updated in place as attempts are made rather than adding a row per attempt. The Attempts column counts the HTTP requests made so far, and a row reads retrying between a failed attempt and the next one, then settles on success or failure.