Token webhook events

Token operations publish typed token.* webhook events alongside the existing transaction.* lifecycle events. Both streams are useful: token.* carries token-specific context (token ID, amount, recipient, role, contract address); transaction.* carries low-level transaction lifecycle.

Delivery semantics

HMAC-SHA256 signed with the per-endpoint secret. See Webhooks.
At-least-once delivery; treat your handler as idempotent (event.id is unique).
Retried with exponential backoff on non-2xx responses.

Event envelope

{
  "id": "evt_01HZ…",
  "type": "token.minted",
  "createdAt": "2026-04-27T10:10:00Z",
  "tenantId": "tenant_…",
  "data": {
    "tokenId": "token_abc123",
    "operationId": "op_mint_123",
    "amount": "1000000000000000000000",
    "recipient": "0x9a8e5e21f0c27d2c5c14b6e9bd8e4a0f9c9b4d12",
    "transactionHash": "0x4ab1…",
    "blockNumber": 1860612
  }
}

Event catalog

Event type	Fires when
`token.created`	A new token configuration is created (status `DRAFT`).
`token.deployment_requested`	Deployment accepted by Qustody.
`token.deployed`	Deployment confirmed on chain. Carries `contractAddress`.
`token.deployment_failed`	Deployment failed during signing or chain submission.
`token.mint_requested`	Mint accepted by Qustody.
`token.minted`	Mint confirmed on chain.
`token.burn_requested`	Burn accepted by Qustody.
`token.burned`	Burn confirmed on chain.
`token.transfer_requested`	Typed token transfer accepted by Qustody.
`token.transferred`	Token transfer confirmed on chain.
`token.role_granted`	On-chain role granted.
`token.role_revoked`	On-chain role revoked.
`token.paused`	Token paused on chain.
`token.unpaused`	Token unpaused on chain.
`token.frozen`	Address frozen on chain.
`token.unfrozen`	Address unfrozen on chain.
`token.compliance_updated`	Compliance configuration updated on chain.
`token.allowlist_added`	Address added to the allowlist.
`token.allowlist_removed`	Address removed from the allowlist.
`token.operation_rejected`	Approver rejected the operation.
`token.operation_failed`	Operation reached terminal `FAILED` state.

Naming convention

Event names follow the existing Qustody convention entity.verb_past. The token.* events match the same shape as transaction.created, deposit.detected, etc.

Sample payloads

`token.deployed`

{
  "id": "evt_01HZ_dep",
  "type": "token.deployed",
  "createdAt": "2026-04-27T10:03:42Z",
  "data": {
    "tokenId": "token_abc123",
    "operationId": "op_deploy_789",
    "contractAddress": "0x9a8e5e21f0c27d2c5c14b6e9bd8e4a0f9c9b4d12",
    "transactionHash": "0x4ab1…",
    "blockNumber": 1860612
  }
}

`token.role_granted`

{
  "id": "evt_01HZ_role",
  "type": "token.role_granted",
  "createdAt": "2026-04-27T10:14:55Z",
  "data": {
    "tokenId": "token_abc123",
    "operationId": "op_role_grant_321",
    "role": "MINTER",
    "subjectAddress": "0x9a8e5e21…",
    "transactionHash": "0x4ab2…"
  }
}

`token.operation_failed`

{
  "id": "evt_01HZ_fail",
  "type": "token.operation_failed",
  "createdAt": "2026-04-27T10:20:00Z",
  "data": {
    "tokenId": "token_abc123",
    "operationId": "op_burn_456",
    "operationType": "BURN",
    "failureReason": "execution reverted: insufficient balance"
  }
}

Subscribing

POST /v1/webhooks
{
  "url": "https://example.com/qustody/hooks",
  "events": ["token.*", "transaction.*", "approval.*"]
}

Getting started

Concepts

Qustody platform

Token management

Reference

Development

Token webhook events

Delivery semantics

Event envelope

Event catalog

Naming convention

Sample payloads

`token.deployed`

`token.role_granted`

`token.operation_failed`

Subscribing

​Delivery semantics

​Event envelope

​Event catalog

​Naming convention

​Sample payloads

​token.deployed

​token.role_granted

​token.operation_failed

​Subscribing

​Related

Delivery semantics

Event envelope

Event catalog

Naming convention

Sample payloads

`token.deployed`

`token.role_granted`

`token.operation_failed`

Subscribing

Related