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

# Event types

> Every event you can subscribe to, and its payload.

These are the events you can subscribe a webhook to. Each marks a stage in the deposit or withdrawal
lifecycle, or a change to a transaction.

Every payload uses the [Version 2 webhook format](/guides/webhooks#version-2): the event data is
wrapped in an envelope carrying an `eventId` and a `data` object.

<Note>
  **Event names are wire values.** They read `partner.customer.*` because that is the identifier the
  platform emits — subscribe with exactly the string shown here. Elsewhere in these docs the people
  they describe are simply called your customers.
</Note>

## Available events

| Event                                                                     | Fires when                                                              |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [`partner.customer.deposit.created`](#customer-deposit-created)           | A deposit has been created for your customer and is waiting to be paid. |
| [`partner.customer.deposit.initiated`](#customer-deposit-initiated)       | Your customer has started the payment.                                  |
| [`partner.customer.deposit.submitted`](#customer-deposit-submitted)       | The payment has been submitted to the bank.                             |
| [`partner.customer.deposit.accepted`](#customer-deposit-accepted)         | The incoming payment has been accepted and reconciled against the bank. |
| [`partner.customer.deposit.failed`](#customer-deposit-failed)             | The deposit could not be processed.                                     |
| [`partner.customer.deposit.completed`](#customer-deposit-completed)       | Funds have settled and the balance is credited.                         |
| [`partner.customer.deposit.expired`](#customer-deposit-expired)           | The deposit was not funded in time and will not complete.               |
| [`partner.customer.withdrawal.requested`](#customer-withdrawal-requested) | A withdrawal has been requested for your customer.                      |
| [`partner.customer.withdrawal.accepted`](#customer-withdrawal-accepted)   | The withdrawal has been accepted for processing.                        |
| [`partner.customer.withdrawal.sent`](#customer-withdrawal-sent)           | The withdrawal has been sent to the beneficiary's bank.                 |
| [`partner.customer.withdrawal.failed`](#customer-withdrawal-failed)       | The withdrawal could not be completed.                                  |
| [`transaction.status.changed`](#transaction-status-changed)               | A transaction moves to a new status.                                    |

<Tip>
  `GET /v1/webhooks/event-types` returns the subscribable event types live, along with the
  properties carried by each one. It is the platform's own list, so it can name an event that is
  registered but not yet emitted — **this page is the published set**. Subscribe to something that
  appears only there and you will simply never be called.
</Tip>

## Deposit events

### partner.customer.deposit.created

A deposit has been created for your customer and is waiting to be paid.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.deposit.created",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "currency": "string",
        "customFields": {},
        "customerCitizenshipCountryCode": "string | null",
        "customerEmail": "string",
        "customerFullName": "string | null",
        "customerGuid": "string | null",
        "customerId": "string",
        "customerResidenceAddress": "string | null",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "partnerName": "string",
        "paymentCountryCode": "string | null",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}
```

***

### partner.customer.deposit.initiated

Your customer has started the payment.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.deposit.initiated",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerGuid": "string | null",
        "customerId": "string",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "paymentCountryCode": "string",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "userIpAddress": "string",
        "websiteReference": "string | null"
    }
}
```

***

### partner.customer.deposit.submitted

The payment has been submitted to the bank.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.deposit.submitted",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerGuid": "string | null",
        "customerId": "string",
        "customerIpAddress": "string",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "paymentCountryCode": "string",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}
```

***

### partner.customer.deposit.accepted

The incoming payment has been accepted and reconciled against the bank.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.deposit.accepted",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "currency": "string",
        "customFields": {},
        "customerEmail": "string | null",
        "customerGuid": "string | null",
        "customerId": "string",
        "debtorAccount": "string",
        "debtorAddress": "string | null",
        "debtorBic": "string",
        "debtorCountryCode": "string",
        "debtorName": "string",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "paymentCountryCode": "string | null",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}
```

***

### partner.customer.deposit.failed

The deposit could not be processed.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.deposit.failed",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerGuid": "string | null",
        "customerId": "string",
        "customerIpAddress": "string",
        "endToEndId": "string",
        "errorDetails": "string | null",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "paymentCountryCode": "string",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}
```

***

### partner.customer.deposit.completed

Funds have settled and the balance is credited. **This is the event to credit your customer on.**

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.deposit.completed",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "blockchainTransactionHash": "string | null",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string | null",
        "customerGuid": "string | null",
        "customerId": "string",
        "debtorAccount": "string",
        "debtorAddress": "string | null",
        "debtorBic": "string",
        "debtorCountryCode": "string",
        "debtorName": "string",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "paymentCountryCode": "string | null",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}
```

***

### partner.customer.deposit.expired

The deposit was not funded in time and will not complete. Terminal — there will be no later `completed` for this reference, so release anything you were holding against it.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.deposit.expired",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "createdAt": "2026-01-01T00:00:00Z | null",
        "currency": "string | null",
        "customFields": {},
        "customerGuid": "string | null",
        "customerId": "string",
        "endToEndId": "string | null",
        "expiryDate": "2026-01-01T00:00:00Z | null",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "reference": "string",
        "websiteReference": "string | null"
    }
}
```

***

## Withdrawal events

### partner.customer.withdrawal.requested

A withdrawal has been requested for your customer.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.withdrawal.requested",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "creditorAccount": "string",
        "creditorAddress": "string | null",
        "creditorBic": "string | null",
        "creditorCountryCode": "string",
        "creditorName": "string",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerGuid": "string | null",
        "customerId": "string",
        "customerIpAddress": "string",
        "customerIpCountryCode": "string",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "reference": "string",
        "websiteReference": "string | null",
        "withdrawalReason": "string"
    }
}
```

***

### partner.customer.withdrawal.accepted

The withdrawal has been accepted for processing.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.withdrawal.accepted",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "creditorAccount": "string",
        "creditorAddress": "string | null",
        "creditorBic": "string | null",
        "creditorCountryCode": "string",
        "creditorName": "string",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerGuid": "string | null",
        "customerId": "string",
        "customerIpAddress": "string",
        "customerIpCountryCode": "string",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "reference": "string",
        "websiteReference": "string | null",
        "withdrawalReason": "string"
    }
}
```

***

### partner.customer.withdrawal.sent

The withdrawal has been sent to the beneficiary's bank.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.withdrawal.sent",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "creditorAccount": "string",
        "creditorAddress": "string | null",
        "creditorBic": "string | null",
        "creditorCountryCode": "string",
        "creditorName": "string",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerGuid": "string | null",
        "customerId": "string",
        "customerIpAddress": "string",
        "customerIpCountryCode": "string",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "reference": "string",
        "websiteReference": "string | null",
        "withdrawalReason": "string"
    }
}
```

***

### partner.customer.withdrawal.failed

The withdrawal could not be completed.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "partner.customer.withdrawal.failed",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "creditorAccount": "string",
        "creditorAddress": "string | null",
        "creditorBic": "string | null",
        "creditorCountryCode": "string",
        "creditorName": "string",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerGuid": "string | null",
        "customerId": "string",
        "customerIpAddress": "string",
        "customerIpCountryCode": "string",
        "errorDetails": "string | null",
        "idempotencyKey": "string | null",
        "partnerCustomerId": "string | null",
        "reference": "string",
        "websiteReference": "string | null",
        "withdrawalReason": "string"
    }
}
```

***

## Transaction events

### transaction.status.changed

A transaction moved to a new status. Covers deposits and withdrawals alike, and is the lightest way to track settlement.

```json theme={null}
{
    "eventId": "uuid",
    "data": {
        "eventType": "transaction.status.changed",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.0,
        "currency": "string",
        "customFields": {},
        "customerGuid": "string | null",
        "idempotencyKey": "string | null",
        "originatingTransactionReference": "string | null",
        "partnerGuid": "string | null",
        "reference": "string",
        "status": "string",
        "transactionHash": "string | null",
        "transactionType": "string",
        "websiteReference": "string | null"
    }
}
```

## Common Fields

### Envelope Fields

The Version 2 envelope wraps every event:

| Field     | Type   | Description                                                                |
| --------- | ------ | -------------------------------------------------------------------------- |
| `eventId` | string | Unique identifier for this webhook delivery, useful for idempotency checks |
| `data`    | object | The event payload containing the fields described in each event section    |

### Base Fields

All event payloads include these fields in the `data` object:

| Field       | Type   | Description                                                    |
| ----------- | ------ | -------------------------------------------------------------- |
| `eventType` | string | The type of event (e.g., `partner.customer.deposit.completed`) |
| `timestamp` | string | ISO 8601 UTC timestamp of when the event occurred              |

### Customer event fields

Every `partner.customer.*` event includes these in its `data` object:

| Field        | Type    | Description                              |
| ------------ | ------- | ---------------------------------------- |
| `customerId` | string  | The unique identifier for the customer   |
| `reference`  | string  | The unique reference for the transaction |
| `amount`     | decimal | The transaction amount                   |
| `currency`   | string  | The currency code (e.g., EUR, USD)       |

### Optional Fields

Many events include these optional fields when provided in the original request:

| Field              | Type           | Description                           |
| ------------------ | -------------- | ------------------------------------- |
| `idempotencyKey`   | string \| null | A key to ensure idempotent processing |
| `websiteReference` | string \| null | Your reference for this transaction   |
| `customFields`     | object \| null | Any additional custom JSON data       |

## Testing Webhook Events

You can test your webhook implementation by using the StableMint sandbox environment. This allows you to simulate different event types and ensure your application handles them correctly.

For more information on how to set up and handle webhooks, please refer to our [Receiving Webhooks](/guides/webhooks) guide.

For any questions or assistance with webhook events, please contact us at [contact@stablemint.io](mailto:contact@stablemint.io).