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
});

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.