# 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'); 
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.swapped.com/swapped-connect/connect-integration/order-notifications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.