Webhooks and WebSockets

Torq writes events to a transactional Postgres outbox only after canonical state commits. AWS FIFO queues preserve each entity ordering key and deduplicate published event IDs.

Webhook envelope

Webhooks are versioned and delivered at least once. Deduplicate by delivery and event ID.

Torq-Signature: t=1784894400,v1=<hex digest>
Torq-Delivery-Id: delivery_...

The v1 digest is HMAC-SHA256 over:

timestamp + "." + deliveryId + "." + exact raw request bytes

Reject timestamps outside five minutes and compare digests in constant time. Endpoints must use HTTPS and resolve only to public network addresses; Torq rechecks DNS at delivery time.

1784894400.whd_0123456789abcdef0123456789abcdef01234567.{"id":"evt_test","type":"vaults.updated","schemaVersion":1,"occurredAt":"2026-07-27T12:00:00.000Z","subject":"vault_test","data":{}}

import crypto from 'node:crypto';

export function verifyTorqWebhook({ rawBody, deliveryId, signature, secret }) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/i.exec(signature);
  if (!match) return false;

  const [, timestamp, given] = match;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${deliveryId}.${rawBody}`, 'utf8')
    .digest('hex');

  return Buffer.byteLength(given, 'hex') === Buffer.byteLength(expected, 'hex') &&
    crypto.timingSafeEqual(Buffer.from(given, 'hex'), Buffer.from(expected, 'hex'));
}

The debugger is intentionally local-only. It never accepts a real webhook secret and cannot replay a delivery from this page. Inspect delivery history with GET /v1/webhook-deliveries and replay a retained delivery from your server with POST /v1/webhook-deliveries/{deliveryId}/replay, an approved secret key, webhooks:write, and a new idempotency key. The API enforces tenant ownership and a 30-day replay window.

The delivery record calculates bounded exponential retry evidence and the AWS queues move exhausted messages to a dead-letter queue. Preview delivery is signed, at-least-once, replayable, and application-scoped. Treat duplicate delivery and reordering across different entities as normal integration conditions; use the delivery ID, event ID, entity key, and cursor to deduplicate and resume.

WebSocket streams

Create a short-lived stream token with POST /v1/stream-token using a server-side secret key. Application-wide polling and streaming are intentionally unavailable to publishable keys, including publishable-key wallet sessions. Subscriptions support event and entity filters, heartbeats, bounded backpressure, reconnect, and cursor resume. Poll GET /v1/events when a stream is unavailable.

{
  "id": "evt_...",
  "type": "vaults.updated",
  "schemaVersion": 1,
  "occurredAt": "2026-07-27T12:00:00.000Z",
  "subject": "vault_...",
  "data": {}
}