---
title: "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.                                   |