Create webhook

Create a webhook with a shown-once whsec_<base64> secret. Standard Webhooks sends webhook-id, webhook-timestamp (Unix seconds), and webhook-signature: v1,<base64 HMAC-SHA256>, signing id.timestamp.rawBody with the base64-decoded key. Verify the exact raw body and enforce five-minute timestamp tolerance. Required API-key scope: `webhooks_manage`; the key's owner must still be allowed to manage webhooks. A member session needs permission to manage webhooks or credentials.

POST /api/v1/workspaces/{workspaceId}/webhooks

Create a webhook

cURL

curl --request POST \
  --url https://api.tetrafi.io/api/v1/workspaces/{workspaceId}/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "events": [],
  "url": "<string>"
}
'

201

{
  "secret": "<string>",
  "secretShownOnce": true,
  "webhook": {
    "active": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "events": [
      "treasury.payout.awaiting_approval"
    ],
    "id": "<string>",
    "updatedAt": "2023-11-07T05:31:56Z",
    "url": "<string>",
    "workspaceId": "<string>",
    "consecutiveFailures": 123,
    "pausedAt": "2023-11-07T05:31:56Z"
  }
}

Authorizations

bearer_authapi_key

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Scopes

webhooks_manage · bearer_auth

webhooks_manage · api_key

Headers

X-Workspace-Id · string<uuid>

The workspace the request acts in. An API key bound to a workspace implies it: omit the header, or send that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

Idempotency-Key · string · required

Required for every caller (1 to 255 bytes; missing or empty is 400 IDEMPOTENCY_KEY_REQUIRED). The same key and body within 24 hours answers the stored 201 again: the same webhook, with secret null and secretShownOnce true, and no second webhook is created. The same key with a different body is 409 IDEMPOTENCY_CONFLICT.

Path Parameters

workspaceId · string · required

Workspace ID

Body

application/json

Request to create a webhook.

events · enum<string>[] · required

Canonical event selectors. Unknown or retired selectors are refused before creation.

Available options: treasury.payout.awaiting_approval, treasury.payout.completed, treasury.payout.failed, treasury.payout.cancelled, treasury.payout.needs_checking, treasury.fiat_leg.planned, treasury.fiat_leg.awaiting_approval, treasury.fiat_leg.payout_held, treasury.fiat_leg.dispatching, treasury.fiat_leg.uncertain, treasury.fiat_leg.in_transit, treasury.fiat_leg.held_by_provider, treasury.fiat_leg.overdue, treasury.fiat_leg.manual_review, treasury.fiat_leg.settled, treasury.fiat_leg.returned, treasury.fiat_leg.returned_after_settlement, treasury.fiat_leg.refunding, treasury.fiat_leg.refunded, treasury.fiat_leg.cancelled, treasury.fiat_leg.refused, treasury.bank_deposit.declared, treasury.bank_deposit.overdue, treasury.bank_deposit.manual_review, treasury.bank_deposit.credited, treasury.bank_deposit.withdrawn_by_user, treasury.bank_deposit.history_unreadable, treasury.bank_deposit.history_recovered, treasury.fiat_leg.awaiting_funds, treasury.fiat_leg.funds_received, treasury.fiat_leg.price_beyond_bound, treasury.fiat_leg.expired_unfunded, treasury.fiat_leg.late_funds, treasury.transfer.submitted, treasury.transfer.awaiting_approval, treasury.transfer.rejected, treasury.transfer.completed, treasury.transfer.failed, treasury.transfer.cancelled, treasury.transfer.custodian_approval_relayed, treasury.transfer.expired, treasury.transfer.replaced, treasury.transfer.confirmation_threshold_set, treasury.run.draft, treasury.run.waiting_for_funds, treasury.run.awaiting_approval, treasury.run.ready, treasury.run.running, treasury.run.waiting, treasury.run.reconciling, treasury.run.needs_review, treasury.run.paused, treasury.run.succeeded, treasury.run.partially_succeeded, treasury.run.failed, treasury.run.recovering, treasury.run.recovered, treasury.run.cancelled, treasury.step.pending, treasury.step.ready, treasury.step.dispatching, treasury.step.waiting, treasury.step.reconciling, treasury.step.needs_review, treasury.step.paused, treasury.step.succeeded, treasury.step.partially_succeeded, treasury.step.failed, treasury.step.cancelled, treasury.step.custodian_cancel_requested, treasury.step.confirmation_threshold_set, treasury.step.custodian_approval_relayed, treasury.step.custodian_cancel_overridden, treasury.approval.requested, treasury.approval.expiring, treasury.approval.approved, treasury.approval.denied, treasury.approval.expired, treasury.destination.retired, treasury.workspace.frozen, treasury.balance.low, treasury.balance.recovered, treasury.statement.ready, treasury.automation.created, treasury.automation.updated, treasury.automation.activated, treasury.automation.returned_to_review, treasury.automation.paused, treasury.automation.resumed, treasury.automation.archived, treasury.agent.envelope.created, treasury.agent.envelope.updated, treasury.agent.kill_switch.activated, treasury.agent.session_signer.granted, treasury.agent.session_signer.revoked, treasury.agent.sponsor.changed, treasury.agent.payment.authorized, treasury.agent.payment.settled, treasury.agent.payment.refused, treasury.agent.payment.received, order.updated, settlement.window.ready, settlement.obligation.due, settlement.obligation.overdue, settlement.payment.matched, settlement.failed, settlement.retried, settlement.disputed, member.invited, member.joined, member.added, member.removed, api_key.rotated, api_key.revoked, api_key.expiring_soon, lp.enabled, lp.disabled, lp.sla_breach, kyb.expiring, kyb.expired, kyb.renewed, kyc.expiring, compliance.sanctions.flag_added, compliance.event, credit.updated, affiliation.invited, affiliation.accepted, affiliation.revoked, bilateral.requested, bilateral.accepted, direct_user.created, direct_user.updated, direct_user.invited, direct_user.suspended, direct_user.verification.pending, direct_user.verification.verified, direct_user.verification.rejected, wallet.session_signer.granted, wallet.session_signer.revoked, webhook.subscription.paused

url · string · required

Response

201

application/json

Webhook created, or the stored creation replayed for the same Idempotency-Key and body (secret null on a replay)

Response after creating a webhook. Store the shown-once whsec_<base64> secret now. Standard Webhooks signs "<webhook-id>.<webhook-timestamp>.<raw body>" with the decoded key bytes, sending webhook-signature: v1,<base64 HMAC-SHA256>. No legacy headers are sent.

secret · string | null · required

Present only on the first response; receipts and replays contain null.

secretShownOnce · boolean · required

True even when the secret has been withheld on replay.

webhook · object · required

A webhook configuration for a workspace.

Show child attributes