Skip to main content
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 typeFires when
token.createdA new token configuration is created (status DRAFT).
token.deployment_requestedDeployment accepted by Qustody.
token.deployedDeployment confirmed on chain. Carries contractAddress.
token.deployment_failedDeployment failed during signing or chain submission.
token.mint_requestedMint accepted by Qustody.
token.mintedMint confirmed on chain.
token.burn_requestedBurn accepted by Qustody.
token.burnedBurn confirmed on chain.
token.transfer_requestedTyped token transfer accepted by Qustody.
token.transferredToken transfer confirmed on chain.
token.role_grantedOn-chain role granted.
token.role_revokedOn-chain role revoked.
token.pausedToken paused on chain.
token.unpausedToken unpaused on chain.
token.frozenAddress frozen on chain.
token.unfrozenAddress unfrozen on chain.
token.compliance_updatedCompliance configuration updated on chain.
token.allowlist_addedAddress added to the allowlist.
token.allowlist_removedAddress removed from the allowlist.
token.operation_rejectedApprover rejected the operation.
token.operation_failedOperation 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

Register a webhook endpoint with a filter: 
POST /v1/webhooks
{
  "url": "https://example.com/qustody/hooks",
  "events": ["token.*", "transaction.*", "approval.*"]
}