# Order Notifications

To receive order notifications, you can provide a <mark style="color:red;">`webhookUrl`</mark> per session as a query parameter. You will receive the notification via the provided URL. In the header of the HTTP request, there’s a signature to validate that the data comes from Swapped.com.

The callback destination is locked at order creation and cannot be changed.

### Callback Config Priority

The system follows a clear priority structure for determining where to send callbacks.

* If a webhookUrl is provided in the iframe initialization URL, this will be used as a priority.
* If a webhookUrl is not set in the iframe initialization, callbacks will be disabled for this order.

This configuration is locked in when the order is created and cannot be changed.

### Best Practices

Order notifications can be resent to account for network errors. As such, <mark style="color:red;">you</mark> <mark style="color:red;"></mark><mark style="color:red;">**must**</mark> <mark style="color:red;"></mark><mark style="color:red;">validate that a transaction has not been credited</mark> before crediting it.

For more information on notification resending, see the [Order Notification Retry Policy](https://docs.swapped.com/#order-notification-retry-policy).

### Callback examples:

#### Payment Pending:

Indicates that the transaction has been created, but the customer hasn't completed payment.

```json
{
  "order_id": "eaf0fcb1-7543-4cad-a712-92caeb25db63",
  "order_crypto_amount": "0.0001",
  "order_crypto": "BTC",
  "order_crypto_address": "2uA6F27wYY6iwtVESsYUhG4VUAxx7mFD4EwMbwxNFmSm",
  "order_status": "payment_pending",
  "order_amount_usd": "5.000252367857236",
  "network": "bitcoin",
  "order_crypto_tag": null,
  "transaction_id": null,
  "external_customer_id": "User-fe1b9",
  "connection": "coinbase_wallet"
}
```

#### Order Completed:

Indicates that the order has been processed, and the sale of cryptocurrency was successful.

```json
{
  "order_id": "eaf0fcb1-7543-4cad-a712-92caeb25db63",
  "order_crypto_amount": "0.0001",
  "order_crypto": "BTC",
  "order_crypto_address": "2uA6F27wYY6iwtVESsYUhG4VUAxx7mFD4EwMbwxNFmSm",
  "order_status": "order_completed",
  "order_amount_usd": "5.000252367857236",
  "network": "bitcoin",
  "order_crypto_tag": null,
  "transaction_id": "9f488e8af23e68d091d171627766dd7224f4f67f84ca2c924dfd11a4a73c3d8c",
  "external_customer_id": "User-fe1b9",
  "connection": "coinbase_wallet"
}
```

<mark style="color:red;">The callbacks below should not be used to credit users and should only be used for analytical purposes.</mark>

**Wallet Order Registered:**

Indicates that a wallet transaction has been created, but has not been confirmed yet .

```json
{
  "order_id": "eaf0fcb1-7543-4cad-a712-92caeb25db63",
  "order_crypto_amount": "0.0001",
  "order_crypto": "BTC",
  "order_crypto_address": "2uA6F27wYY6iwtVESsYUhG4VUAxx7mFD4EwMbwxNFmSm",
  "order_status": "wallet_order_registered",
  "order_amount_usd": "5.000252367857236",
  "network": "bitcoin",
  "order_crypto_tag": null,
  "transaction_id": null,
  "external_customer_id": "User-fe1b9",
  "connection": "coinbase_wallet"
}
```

**Wallet Order Confirmed:**

Indicates that a wallet transaction has been confirmed and the order has been completed.

```json
{
  "order_id": "eaf0fcb1-7543-4cad-a712-92caeb25db63",
  "order_crypto_amount": "0.0001",
  "order_crypto": "BTC",
  "order_crypto_address": "2uA6F27wYY6iwtVESsYUhG4VUAxx7mFD4EwMbwxNFmSm",
  "order_status": "wallet_order_confirmed",
  "order_amount_usd": "5.000252367857236",
  "network": "bitcoin",
  "order_crypto_tag": null,
  "transaction_id": null,
  "external_customer_id": "User-fe1b9",
  "connection": "coinbase_wallet"
}
```

### Response Definition:

* <mark style="color:red;">`order_id`</mark>: The order ID on Swapped.com.
* <mark style="color:red;">`order_crypto_amount`</mark>: The exact cryptocurrency amount you will receive.
* <mark style="color:red;">`order_crypto`</mark>: The cryptocurrency you receive.
* <mark style="color:red;">`order_status`</mark>: The current status of the order.
* <mark style="color:red;">`order_crypto_address`</mark>: The cryptocurrency address where you receive the cryptocurrency.
* <mark style="color:red;">`external_customer_id`</mark>: Your customer's ID (If provided in the URL).
* <mark style="color:red;">`order_amount_usd`</mark>: The <mark style="color:orange;">`order_crypto_amount`</mark> converted to USD.
* <mark style="color:red;">`order_crypto_tag`</mark>: The destination tag/memo of the order (used with XRP)
* <mark style="color:red;">`network`</mark>: The network used to send transactions.
* <mark style="color:red;">`transaction_id`</mark>: The crypto transaction hash.
* <mark style="color:red;">`connection`</mark>: The connection used for the transaction. Provided as <mark style="color:orange;">`provider`</mark> for exchanges and <mark style="color:orange;">`provider_wallet`</mark> for wallets (e.g. <mark style="color:orange;">`phantom_wallet`</mark> , <mark style="color:orange;">`binance`</mark> )

### Order State Flows

Currently, an order can follow only one flow that is applied when an order gets completed successfully and the user receives crypto:

<mark style="color:red;">`payment_pending`</mark> → <mark style="color:red;">`order_completed`</mark>

### The signature:

Compute an HMAC with a SHA-256 hash function. Use your secret API key as the key and use the request body as the message. Compare this to the signature sent in the <mark style="color:orange;">`x-signature`</mark> request header.

#### Example with NodeJS:

```javascript
import crypto from 'crypto';

const secretKey = 'sk_test_key'; // Replace with your secret key
const requestBody = `{"order_id":"eaf0fcb1-7543-4cad-a712-92caeb25db63","order_crypto_amount":"0.0001","order_crypto":"BTC","order_crypto_address":"2uA6F27wYY6iwtVESsYUhG4VUAxx7mFD4EwMbwxNFmSm","order_status":"completed","order_amount_usd":"5.000252367857236","network":"bitcoin","transaction_id":"9f488e8af23e68d091d171627766dd7224f4f67f84ca2c924dfd11a4a73c3d8c","external_customer_id":"User-fe1b9"}`;

const signature =
  crypto
    .createHmac('sha256', secretKey)
    .update(requestBody)
    .digest('base64'); 
```