Skip to content

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.

Local inspection only

Event debugger

Inspect an event envelope and the exact v1 signing input without sending payloads or webhook secrets to Torq. Delivery history and replay remain application-scoped server operations.

Do not paste a production webhook secret here. Use the server verifier below in the service that owns your endpoint. This inspector stores nothing and makes no network request.

Envelope inspection

Payload is valid JSON.

  • idevt_test
  • typevaults.updated
  • schemaVersion1
  • occurredAt2026-07-27T12:00:00.000Z
  • subjectvault_test
  • data[object Object]

Signature header has the supported v1 shape.

Signing input

Torq signs exactly timestamp.deliveryId.rawBody; parse JSON only after verification.

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

Fixed test-vector verification

Runs Web Crypto against a public, non-production vector only.

Server verifier and replay boundary

Verify a real delivery where its secret is held. To replay a retained delivery, call POST /v1/webhook-deliveries/{deliveryId}/replay from your server with an approved secret key, webhooks:write, and a fresh idempotency key. The replay keeps the original application boundary and 30-day expiry check.

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.

Event catalog

Generated from the active developer capability registry. Entries follow the Private Previewrelease channel and use the versioned Torq event envelope.

activity.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
allocation.intelligence.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
assets.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
credit.facilities.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
deployments.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
eligibility.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
entities.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
fees.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
funds.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope
liquidation.recovery.updated
Review
At least once; deduplicate by event and delivery ID.
schemaVersion in every event envelope

Envelope schema

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