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

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.

1
{
2
  "action": "<webhook.name>",
3
  "account_id": "acct_xxxxxxx",
4
  "environment_id": "env_xxxxxxxx",
5
  "object_type": "<object>",
6
  "body": {},
7
  // if applicable
8
  "company_id": "comp_xxxxxxxx",
9
  "feature_id": "feat_xxxxxxxx"
10
}

The contents of body vary depending on the event. You can inspect real payloads using free services like Webhook-Test 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:

1
import { verifyWebhookSignature } from "@schematichq/schematic-typescript-node";
2
3
// Express example
4
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
5
  try {
6
    verifyWebhookSignature(req, process.env.SCHEMATIC_WEBHOOK_SECRET, req.body);
7
  } catch (err) {
8
    return res.status(400).send("Invalid signature");
9
  }
10
11
  const event = JSON.parse(req.body.toString());
12
  // handle event...
13
  res.sendStatus(200);
14
});

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. Retries use exponential backoff with jitter, up to 5 retries after the initial attempt (6 delivery attempts in total). Once those attempts are exhausted, the event is not delivered 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. 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.