Webhooks

Concepts: Which webhook fires when

TCB signs and POSTs an event to your endpoint when something terminal happens to your money or your registry, so you do not have to poll. Every route on this page needs scope webhook:manage and acts as you: they refuse x-on-behalf-of with 400 ON_BEHALF_OF_NOT_ALLOWED_HERE. A sub-client holds no subscription of its own, so an event about one of your sub-clients arrives on your endpoint.

curl -X POST https://api.threecommabank.com/api/partner/v1/webhooks \
  -H "Authorization: Bearer $TCB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://partner.example.com/tcb/webhooks",
    "events": ["deposit.settled", "withdrawal.settled", "transfer.completed"]
  }'

{
  "success": true,
  "data": {
    "webhookId": "4e8b1d70-a35c-4692-b0f1-9d2c6a4e73b8",
    "url": "https://partner.example.com/tcb/webhooks",
    "events": ["deposit.settled", "withdrawal.settled", "transfer.completed"],
    "status": "ACTIVE",
    "secret": "whsec_k3vJ9aQ2mR7xL0pT4wZ8nB1yC6dF5gH2jK9sV3eA7uQ",
    "secretPreview": "whsec_k3vJ9aQ2…",
    "previousSecretExpiresAt": null,
    "createdAt": "2026-09-02T10:15:28.000Z",
    "disclosure": { "version": "2026-09-06", "summary": "…", "items": ["…"] }
  },
  "timestamp": "2026-09-02T10:15:28.377Z"
}

{
  "id": "9c1e5b3a-7d24-4f80-b6a1-2e5c9017a4f6",
  "type": "deposit.settled",
  "occurredAt": "2026-09-02T10:15:34.000Z",
  "resource": { "type": "deposit", "id": "2f6c9a41-3e58-4b70-9d12-6a8f0c3e5b71" },
  "disclosure": { "version": "2026-09-06", "summary": "…", "items": ["…"] }
}

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyTcbWebhook(header, rawBody, secret, toleranceSeconds = 300) {
  const parts = header.split(',').map((p) => p.trim());
  const t = parts.find((p) => p.startsWith('t='))?.slice(2);
  if (!t || !/^\d+$/.test(t)) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  const expected = Buffer.from(
    createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'),
    'utf8',
  );

  return parts
    .filter((p) => p.startsWith('v1='))
    .some((p) => {
      const candidate = Buffer.from(p.slice(3), 'utf8');
      return (
        candidate.length === expected.length && timingSafeEqual(candidate, expected)
      );
    });
}

tcb-webhook-signature: t=1788344134,v1=0797ff9b1a6ba4aa039e3d6f3a93eacd760518b89981e5f5d96577887fe63302

curl https://api.threecommabank.com/api/partner/v1/deposits/2f6c9a41-3e58-4b70-9d12-6a8f0c3e5b71 \
  -H "Authorization: Bearer $TCB_API_KEY"

Event catalogue

The step-by-step chain uses five resource types: token_mint, token_redemption, share_subscription, share_redemption and share_redemption_request. Fetch each at the path in the table — /token-mints/{id}, /token-redemptions/{id}, /share-subscriptions/{id}, /share-redemptions/{id} and /share-redemption-requests/{id}. The paths use hyphens and the types use underscores, so map them rather than building the path from the type. A part the vault pays on a queued redemption fires no event of its own: the request's queue.fills lists each one, and share_redemption_request.settled fires when the request closes.

Two absences are contractual: a compensable failure fires no event, and there is no transfer.failed. Both are explained under which webhook fires when.

Three more absences are deliberate on CommaNet. There is no settlement.failed, for the same reason there is no transfer.failed. There is no settlement.hold.expired, because a hold has no clock — it ends because somebody ended it. And there is no event for a request or a return that its own author cancelled: withdrawing your own ask tells the other side nothing it needs to act on.

CommaNet events reach both parties where both hold a subscription, so a settlement you received arrives on your registry as settlement.settled with direction: "IN" on the fetched row.

Retry ladder

An attempt fails on a non-2xx status, a connection error, a redirect, or a response that has not arrived within 10 seconds. TCB then retries on a fixed ladder. Every step follows a real failed attempt.

Seven attempts in all. When the ladder runs out, the delivery is parked as exhausted; ask TCB to replay it. A disabled subscription attempts nothing and consumes no attempts, so re-enabling it resumes what was owed. Signatures are computed at attempt time, so a retry after a rotation is signed with the secret set in force at that moment.

Rotate the signing secret

POST /webhooks/{id}/rotate-secret · scope webhook:manage

Mints a new secret, returns it in full exactly once, and sets previousSecretExpiresAt 24 hours out. Until that moment every delivery is signed with both secrets, as two v1= entries, so whichever secret your servers hold verifies. Cut over at your own pace. After that moment only the new secret signs.

curl -X POST https://api.threecommabank.com/api/partner/v1/webhooks/4e8b1d70-a35c-4692-b0f1-9d2c6a4e73b8/rotate-secret \
  -H "Authorization: Bearer $TCB_API_KEY"

{
  "success": true,
  "data": {
    "webhookId": "4e8b1d70-a35c-4692-b0f1-9d2c6a4e73b8",
    "url": "https://partner.example.com/tcb/webhooks",
    "events": ["deposit.settled", "withdrawal.settled", "transfer.completed"],
    "status": "ACTIVE",
    "secret": "whsec_R8pW2nY6cH0jD4tK7bQ1xF5mZ3vA9sL2gN6eU0iT4rB",
    "secretPreview": "whsec_R8pW2nY6…",
    "previousSecretExpiresAt": "2026-09-03T10:15:30.000Z",
    "createdAt": "2026-09-02T10:15:28.000Z",
    "disclosure": { "version": "2026-09-06", "summary": "…", "items": ["…"] }
  },
  "timestamp": "2026-09-02T10:15:30.221Z"
}

Rotating again inside an open window replaces the previous secret immediately. At most two secrets are ever valid, and the response always states the current window. Keep verifying against both until previousSecretExpiresAt has passed.

Manage your endpoints

An id that is not yours answers 404 WEBHOOK_SUBSCRIPTION_NOT_FOUND. Another principal's subscriptions do not exist as far as this API is concerned.

Best practices

• Answer 2xx first, process second. Queue the event id and return. Your handler has 10 seconds.
• Dedupe on the event id. Delivery is at-least-once, and the same event can arrive more than once.
• Assume no ordering. A withdrawal.settled can reach you before an earlier deposit.settled. Order your own work by the object you fetch, not by arrival.
• Fetch the resource; do not trust the payload for state. The body carries a pointer, not a snapshot. Act on the object as it stands when you read it.
• Verify before parsing, over the raw bytes, in constant time, against every v1 entry.
• Subscribe to the failure events too. deposit.failed, withdrawal.failed and conversion.failed are the only events that tell you a flow ended without money moving.

Handle the errors

The full catalogue is in Errors.

The machine-readable specification for these endpoints is openapi.partner.v1.json. Where it and this page disagree, the specification is authoritative.

Pilot disclosure