Webhooks

Webhooks push events to your server as they happen, so you don’t have to poll. When something changes in a tenant — a bill is created, an order is fulfilled, stock runs low — Vantr sends an HTTPS POST to the endpoints you’ve registered. Every delivery is signed with a per-endpoint secret so you can prove it came from us and was not tampered with, and deliveries are retried with backoff so a brief outage on your side doesn’t drop events.

Register an endpoint

Register endpoints in the developer portal under Webhooks, or programmatically with the /v2/webhooks API (scopes webhooks.read / webhooks.write):

curl -X POST https://api.vantr.ai/v2/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.yourapp.com/vantr",
    "events": ["invoice.created", "invoice.paid", "order.fulfilled"]
  }'

{
  "success": true,
  "webhook": {
    "id": "5f1c…",
    "url": "https://hooks.yourapp.com/vantr",
    "events": ["invoice.created", "invoice.paid", "order.fulfilled"],
    "active": true,
    "signed": true,
    "secret": "whsec_9b2f…"
  }
}

The signing secret is returned only once, on create. Store it securely — you’ll need it to verify deliveries. If you lose it, rotate it with PATCH /v2/webhooks/{id} (sending a new secret) and update your server. Omit events (or send []) to subscribe to everything.

Endpoints must be public HTTPS URLs. Plain http://, localhost, and private / internal / link-local hosts are rejected at save time, and re-checked (with DNS resolution) before every delivery to prevent SSRF.

The request we send

POST /vantr HTTP/1.1
Content-Type: application/json
X-Webhook-Id: 3a0e8b6c-…              ← unique per delivery; use it to dedupe
X-Webhook-Event: invoice.created
X-Webhook-Signature: t=1719360000,v1=4f1e…  ← HMAC, see below

{
  "id": "3a0e8b6c-…",
  "event": "invoice.created",
  "tenant_id": "…",
  "timestamp": "2026-06-25T12:00:00.000Z",
  "data": { … }
}

Verify the signature

X-Webhook-Signature has two parts:

t — the unix timestamp (seconds) when we signed the delivery.
v1 — HMAC_SHA256(secret, "{t}.{rawBody}") as hex.

To verify a delivery:

Read the raw request body (the exact bytes — don’t re-serialize a parsed object).
Parse t and v1 from X-Webhook-Signature.
Recompute HMAC_SHA256(secret, "{t}.{rawBody}") and constant-time compare it to v1.
Reject deliveries whose t is outside your tolerance window (we recommend ±5 minutes) to prevent replay.

const crypto = require('crypto');

function verifyVantrWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((kv) => kv.split('='))
  );
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!Number.isFinite(t) || !v1) return false;

  // Replay protection
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;

  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express — capture the RAW body for verification:
app.post('/vantr', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8');
  if (!verifyVantrWebhook(raw, req.get('X-Webhook-Signature'), process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('bad signature');
  }
  const event = JSON.parse(raw);
  // Dedupe on event.id (X-Webhook-Id) — deliveries are at-least-once.
  res.sendStatus(200); // ack fast; do the work asynchronously
  // … enqueue event for processing …
});

Delivery, retries, and idempotency

Acknowledge fast. Respond 2xx within ~10 seconds. Any non-2xx (or a timeout, connection error, or redirect — we do not follow redirects) is treated as a failed delivery.
Retries. Failed deliveries are retried with exponential backoff and jitter (≈30s, 1m, 2m, … up to ~1h) for several attempts over a few hours, then marked dead. The retried request is byte-identical (same X-Webhook-Id, same body, same signature).
At-least-once. A delivery can arrive more than once (e.g. you 2xx’d but we didn’t see it). Make your handler idempotent by deduping on X-Webhook-Id.
Order is not guaranteed. Use the timestamp / your own state to resolve ordering if it matters.

Events

Event	Fires when
`invoice.created`	A bill (AP invoice) is created
`invoice.updated`	A bill is updated
`invoice.paid`	A bill is marked paid
`vendor.created`	A vendor is created
`vendor.updated`	A vendor is updated
`inventory.low_stock`	An item drops to/below its reorder point
`inventory.count_completed`	An inventory count is approved
`order.created`	An order is created (e.g. a POS sale completes)
`order.updated`	An order is invoiced/updated
`order.fulfilled`	An order is fulfilled

Subscribe to specific events with the events array, use a prefix.* wildcard (e.g. invoice.*), or subscribe to everything by omitting events.

Start

Build

Operate

Webhooks

Webhooks

Register an endpoint

The request we send

Verify the signature

Delivery, retries, and idempotency

Events

​Webhooks

​Register an endpoint

​The request we send

​Verify the signature

​Delivery, retries, and idempotency

​Events

Webhooks

Register an endpoint

The request we send

Verify the signature

Delivery, retries, and idempotency

Events