Skip to content
Truss Docs

Webhooks

Truss webhooks send HTTP POST requests to your URLs when database rows change. They use the same LISTEN/NOTIFY infrastructure as realtime subscriptions, with added features like HMAC signing, retry tracking, and delivery logs.

Creating a webhook

Via dashboard

Navigate to Webhooks in the sidebar. Click “Create Webhook” and configure:

  • Name — a label for the webhook
  • Table — which table to watch
  • Events — INSERT, UPDATE, DELETE (pick one or more)
  • URL — the endpoint to call
  • Headers — optional custom headers (e.g., Authorization)
  • Secret — for HMAC signature verification

Via API

Terminal window
curl -X POST http://localhost:8787/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New order notification",
    "table_schema": "public",
    "table_name": "orders",
    "events": ["INSERT"],
    "url": "https://your-app.com/webhooks/new-order",
    "headers": {"Authorization": "Bearer your-secret"},
    "secret": "whsec_your_signing_secret",
    "active": true
  }'

Webhook payload

When an event fires, Truss sends a POST request with this JSON body:

{
  "event": "INSERT",
  "schema": "public",
  "table": "orders",
  "row": {
    "id": 42,
    "user_id": 1,
    "total": 99.99,
    "created_at": "2025-01-15T10:00:00Z"
  },
  "old_row": null,
  "timestamp": "2025-01-15T10:00:00.123Z"
}

For UPDATE events, both row (new data) and old_row (previous data) are included.

HMAC signing

If you set a secret on the webhook, Truss signs each payload with HMAC-SHA256. The signature is sent in the X-Truss-Signature header.

Verify it in your handler:

import crypto from 'crypto';


function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Managing webhooks

Terminal window
# List all webhooks
curl http://localhost:8787/api/webhooks


# Update a webhook
curl -X PATCH http://localhost:8787/api/webhooks/{id} \
  -H "Content-Type: application/json" \
  -d '{"active": false}'


# Delete a webhook
curl -X DELETE http://localhost:8787/api/webhooks/{id}

Testing and replaying

Send a test event

Terminal window
curl -X POST http://localhost:8787/api/webhooks/{id}/test

Sends a test payload to the webhook URL and returns the response status.

View delivery logs

Terminal window
curl http://localhost:8787/api/webhooks/{id}/logs

Each log entry includes:

  • event_type — INSERT, UPDATE, DELETE, or TEST
  • payload — the JSON that was sent
  • status_code — HTTP response status
  • response_body — response from your server
  • latency_ms — round-trip time

Replay a delivery

Terminal window
curl -X POST http://localhost:8787/api/webhooks/{id}/replay/{logId}

Re-sends the exact same payload from a previous delivery.

Failure tracking

Truss tracks consecutive failures per webhook via fail_count. The dashboard shows which webhooks are healthy and which are failing. You can pause failing webhooks and resume them after fixing the endpoint.

Client API

Webhooks are available via the management API:

Terminal window
curl http://localhost:8787/v1/webhooks \
  -H "apikey: truss_sk_your_key"


curl http://localhost:8787/v1/webhooks/{id} \
  -H "apikey: truss_sk_your_key"