Developer Platform
External account events
Coming soon. External account webhook events are not yet available in production. The
payee.setup.*event types are planned but have not been released. Do not build against them today; this page will be updated when they ship.
External account events will notify you about the progress of asynchronous external account registration. After POST /v1/external-accounts returns 202 Accepted, a background worker registers the account with the underlying payment partners.
When external account events are sent
Gravv sends an external account event when:
- The external account is fully registered and its status changes to active.
- A registration attempt fails temporarily and the worker schedules a retry.
- Registration fails after the maximum number of retries.
External account event types
The following event types are available for external accounts:
| Event type | Description |
|---|---|
| payee.setup.completed | external account fully registered; status flipped to active |
| payee.setup.retrying | transient failure; worker will retry automatically |
| payee.setup.failed | max attempts exceeded; manual reconciliation may be required |
External account event structure
Every external account event contains the following fields:
| Field | Type | Description |
|---|---|---|
| event_type | string | completed, retrying, or failed |
| payee_id | uuid | identifier of the external account (matches the id from POST) |
| tenant_id | uuid | identifier of your business |
| occurred_at | string | ISO-8601 timestamp |
Additional fields on retrying and failed
The retrying and failed events include all of the fields in the preceding section, and three additional fields:
| Field | Type | Description |
|---|---|---|
| attempts | integer | attempt number that produced this event (starts at 1) |
| reason_code | string | stable enum for branching client logic. Today's values: temporary_unavailable, max_retries_exceeded. More may be added. |
| client_message | string | user-facing message safe to render verbatim. Does not include raw upstream error strings. |
Was this page helpful?