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

# gVault statuses and event types

> Interpret fee-wrapper, mutation, and webhook-delivery states consistently.

## Fee-wrapper lifecycle

| Status         | Meaning                                                                | Application action                                                 |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `provisioning` | Ground accepted the request and deployment/configuration is incomplete | Persist the IDs and wait                                           |
| `ready`        | The wrapper address is deployed and authorized against its gVault      | Enable customer access and onchain use                             |
| `failed`       | Provisioning reached a terminal failure                                | Surface the error and contact Ground before creating a replacement |

## Allowlist and fee-update lifecycle

Mutation responses use `confirmed` when the requested state is already effective
and `submitted` when Ground broadcast an onchain transaction. Webhooks report
the terminal `confirmed` or `failed` result.

Do not convert `submitted` to `confirmed` based only on time elapsed. Read the
resource, observe the transaction receipt, or process the confirming webhook.

## gVault webhook event types

| Event                                  | Resource                       | Important payload fields                                        |
| -------------------------------------- | ------------------------------ | --------------------------------------------------------------- |
| `gvault.allowlist.status_changed`      | Direct gVault authorization    | `gVaultId`, `address`, `status`, `transactionHash`, `error`     |
| `fee_wrapper.status_changed`           | Fee-wrapper provisioning       | `feeWrapperId`, `status`, `contractAddress`, `error`            |
| `fee_wrapper.fees.status_changed`      | Fee configuration update       | `feeWrapperId`, `status`, `transactionHash`, `error`            |
| `fee_wrapper.allowlist.status_changed` | Wrapper customer authorization | `feeWrapperId`, `address`, `status`, `transactionHash`, `error` |

Every delivery uses `{ id, type, createdAt, data }`; the fields above are inside
`data`. Treat identifiers and the current resource read as authoritative;
webhook arrival order is not guaranteed.

## Delivery status

The event-feed API describes delivery to your registered endpoint:

| Status      | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| `pending`   | Delivery has not completed                                        |
| `completed` | Your endpoint accepted the delivery                               |
| `failed`    | Delivery did not complete; inspect `attemptCount` and `lastError` |

Delivery status is not business-operation status. For example, a successfully
delivered `status: failed` fee-update event has delivery status `completed` and
payload status `failed`.

See [Integrate gVault webhooks](/docs/gvaults/webhooks) for receiver setup and
[Handle asynchronous gVault operations](/docs/gvaults/async-operations) for the
full reconciliation model.