Webhooks

​

How it works

​

Event types

​

Wildcard filters

​

Endpoint limits by plan

​

Creating an endpoint

1. In the tenant console, go to Settings > Webhooks.
2. Click Add endpoint.
3. Enter a name, your HTTPS destination URL, and select the event types you want to receive.
4. Click Create.

​

Via the API

POST /v1/webhooks/endpoints
X-API-Key: tl_live_...
Content-Type: application/json

{
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "event_filters": ["attestation.*", "verification.completed"]
}

{
  "id": "ep_abc123",
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "status": "active",
  "secret": "whsec_...",
  "event_filters": ["attestation.*", "verification.completed"],
  "created_at": "2026-03-25T12:00:00Z"
}

​

Listing endpoints

GET /v1/webhooks/endpoints
X-API-Key: tl_live_...

​

Verifying signatures

X-Truthlocks-Signature: t=1710000000,v1=a1b2c3d4e5f6...

1. Extract t (timestamp) and v1 (signature) from the header.
2. Reject the request if the timestamp is more than 5 minutes old.
3. Concatenate {timestamp}.{raw_request_body} to form the signing string.
4. Compute HMAC-SHA256 of the signing string using your endpoint secret.
5. Compare the computed digest to v1 using a constant-time comparison.

import crypto from "crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/truthlock", (req, res) => {
  const sigHeader = req.headers["x-truthlocks-signature"] as string;
  if (!sigHeader) return res.status(401).send("Missing signature");

  const parts = Object.fromEntries(
    sigHeader.split(",").map((p) => p.split("=") as [string, string])
  );
  const timestamp = parts["t"];
  const signature = parts["v1"];

  // Reject stale requests (5-minute window)
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return res.status(401).send("Timestamp expired");

  // Compute expected signature
  const signingString = `${timestamp}.${req.body.toString()}`;
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(signingString)
    .digest("hex");

  // Constant-time comparison
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString());
  console.log("Received event:", event.type);

  res.status(200).json({ received: true });
});

​

Request headers

​

Retry behavior

GET /v1/webhooks/endpoints/{id}/deliveries
X-API-Key: tl_live_...

​

Rotating secrets

1. In the tenant console, go to Settings > Webhooks and click on the endpoint.
2. Click Rotate secret.
3. Copy the new secret — the old secret stops working immediately.

POST /v1/webhooks/endpoints/{id}/rotate
X-API-Key: tl_live_...

​

Testing webhooks

1. In the tenant console, go to Settings > Webhooks and click on the endpoint.
2. Click Send test.
3. A webhook.test event is sent to your URL using the full signing and delivery pipeline.

POST /v1/webhooks/test-delivery
X-API-Key: tl_live_...
Content-Type: application/json

{
  "endpoint_id": "ep_abc123",
  "event_type": "webhook.test",
  "payload": { "status": "ok", "source": "test-delivery" }
}

​

Best practices

• Verify every signature. Never skip signature verification, even in development.
• Use a message queue. Enqueue incoming events and process them in a worker to avoid blocking the HTTP response.
• Handle duplicates. Use the X-Truthlocks-Event-Id header to deduplicate events in case of retries.
• Monitor delivery failures. Check the deliveries tab in the console regularly for failed or dead deliveries.
• Keep secrets secure. Store your webhook secret in environment variables, not in source code.