# Conversions Webhooks

## Overview

Ryft emits webhook events when a conversion is created or updated. See the [Conversions guide](/documentation/get_started/conversions) for guidance on how to respond to these events.

## Conversion Events

Conversion.created
Emitted when a conversion is created. The `rate`, `buy.amount`, `sell.fees`/`buy.fees`, and `estimatedSettlementDate` are not present — pricing is applied asynchronously.

```json Conversion.created - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Conversion.created",
    "data": {
        "id": "cv_XXXXXXXX",
        "sell": {"amount": 100000, "currency": "EUR"},
        "buy": {"currency": "GBP"},
        "status": "InProgress",
        "reason": "Monthly EUR settlement",
        "createdTimestamp": 1750000000
    },
    "accountId": "ac_XXXXXXXX",
    "createdTimestamp": 1750000000,
    "lastUpdatedTimestamp": 1750000000,
    "deliveryStatus": "Success"
}
```

Conversion.updated (priced)
Emitted when the exchange rate has been applied. The `rate`, `buy.amount`, and `sell.fees`/`buy.fees` are now populated. Use this event to present the priced outcome to the account holder.

The fee is charged on exactly one side, so read `fees` from whichever of `sell` or `buy` carries it. This example is for a Sub-Account conversion charged on the buy side, so the fee breakdown carries `platform` (which includes Ryft's fee):

```json Conversion.updated (priced) - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Conversion.updated",
    "data": {
        "id": "cv_XXXXXXXX",
        "sell": {"amount": 100000, "currency": "EUR"},
        "buy": {
            "amount": 86000,
            "currency": "GBP",
            "fees": {
                "platform": {
                    "amount": 1000,
                    "ryftFee": {"amount": 700}
                }
            }
        },
        "rate": 0.86,
        "status": "InProgress",
        "reason": "Monthly EUR settlement",
        "estimatedSettlementDate": "2026-06-20",
        "createdTimestamp": 1750000000
    },
    "accountId": "ac_XXXXXXXX",
    "createdTimestamp": 1750000300,
    "lastUpdatedTimestamp": 1750000300,
    "deliveryStatus": "Success"
}
```

For a conversion on your own account, `fees` carries `ryft` instead:

```json Conversion.updated (priced) - Own account buy
{
    "amount": 86000,
    "currency": "GBP",
    "fees": {
        "ryft": {"amount": 700}
    }
}
```

Where the fee is charged on the sell side, `fees` sits on `sell` and `buy` carries none — the fee came off before the conversion, so the full `buy.amount` is credited:

```json Conversion.updated (priced) - Sell-side fee
{
    "sell": {
        "amount": 100000,
        "currency": "EUR",
        "fees": {
            "ryft": {"amount": 700}
        }
    },
    "buy": {"amount": 85398, "currency": "GBP"}
}
```

See [Fees and FX margin](/documentation/get_started/conversions#fees-and-fx-margin) for the fee shapes, and [Calculating the net amount and effective rate](/documentation/get_started/conversions#calculating-the-net-amount-and-effective-rate) to derive the credited amount.

Conversion.updated (settled)
Emitted when the conversion settles. The `status` is `Settled`, `settledTimestamp` is set, and the bought funds are credited to the account's balance.

As above, this is a Sub-Account conversion charged on the buy side — see [Fees and FX margin](/documentation/get_started/conversions#fees-and-fx-margin) for the fee breakdown.

```json Conversion.updated (settled) - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Conversion.updated",
    "data": {
        "id": "cv_XXXXXXXX",
        "sell": {"amount": 100000, "currency": "EUR"},
        "buy": {
            "amount": 86000,
            "currency": "GBP",
            "fees": {
                "platform": {
                    "amount": 1000,
                    "ryftFee": {"amount": 700}
                }
            }
        },
        "rate": 0.86,
        "status": "Settled",
        "reason": "Monthly EUR settlement",
        "estimatedSettlementDate": "2026-06-20",
        "settledTimestamp": 1750086400,
        "createdTimestamp": 1750000000
    },
    "accountId": "ac_XXXXXXXX",
    "createdTimestamp": 1750086400,
    "lastUpdatedTimestamp": 1750086400,
    "deliveryStatus": "Success"
}
```