> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Token webhook events

> Event types, payload schema, and delivery semantics for token-management webhooks.

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](/concepts/webhooks).
* At-least-once delivery; treat your handler as idempotent (`event.id` is unique).
* Retried with exponential backoff on non-2xx responses.

## Event envelope

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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:

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

## Related

* [Webhooks (concept)](/concepts/webhooks)
* [Token operation lifecycle](/qustody/token-management/token-operation-lifecycle)
* [Token operations endpoint](/api-reference/tokens/list-token-operations)