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

# Webhook Configuration

> Receive real-time notifications for transaction status updates

<Note>
  Webhooks are optional but recommended for tracking transaction status in real-time.
</Note>

## Overview

Webhooks allow you to receive automatic notifications when order events occur. Configure them in your Rampnow Partner Dashboard to stay updated on transaction statuses without polling.

## Configuration Steps

<Steps>
  <Step title="Access API Hub">
    Navigate to the **API Hub** in your [Rampnow Partner Dashboard](https://partner.rampnow.io/api/auth/signin?callbackUrl=%2F).
  </Step>

  <Step title="Add Webhook URL">
    Enter your server endpoint URL that will receive webhook notifications.

    <Warning>
      Ensure you have a dedicated API endpoint set up on your server to handle incoming webhook events.
    </Warning>
  </Step>

  <Step title="Select Event Types">
    Choose which events to receive:

    * **All events** - Get notified of every status change
    * **Specific events** - Select only the events you need
  </Step>
</Steps>

***

## Order Events

Your webhook will receive notifications for these order status changes:

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem'}}>
  <Card title="Processing" icon="spinner">
    Order is being processed
  </Card>

  <Card title="Completed" icon="circle-check">
    Order successfully completed
  </Card>

  <Card title="Failed" icon="circle-xmark">
    Order failed or was cancelled
  </Card>
</div>

***

## Implementation Example

Here's a simple Flask server that receives webhook notifications:

<CodeGroup>
  ```python Python (Flask) theme={null}
  from flask import Flask, request, jsonify
  app = Flask(__name__)
  @app.route('/order/external', methods=['POST'])
  def orderwebhook():
      data = request.json  
      # partner logic based on event
      return jsonify({"status": "success"}), 200
  if __name__ == '__main__':
      app.run(port=3000)

  ```
</CodeGroup>

<Tip> Always return a `200 OK` response to acknowledge receipt of the webhook. </Tip>

## Webhook Payload Schema

<Info>Find different tabs below for each product wise webhook formats.</Info>

<CodeGroup>
  ```json On/Off Ramp Orders theme={null}
  {
    "createdAt": "2024-10-01T12:00:00Z",
    "eventUid": "853d470c-db91-4c6e-9724-acfccd138306",
    "eventType": "ramp_orders.processing",
    "payload": {
      "orderUid": "5de57551-3272-4af5-86a4-5eeae6ccc37f",
      "externalOrderUid": "1eda87a5-dcfb-4a14-89d9-d0384bcb4ead",
      "createTime": "2024-10-01T11:59:45",
      "updateTime": "2024-10-01T12:00:00Z",
      "partnerGeneratedUid": "707966cf-afc0-4577-bd42-cd79a5b6f629",
      "orderType": "buy",
      "orderStatus": "processing",
      "paymentStatus": "settled",
      "paymentMode": "card",
      "srcCurrency": "USD",
      "srcChain": "fiat",
      "srcAmount": 100,
      "dstCurrency": "ETH",
      "dstChain": "ethereum",
      "dstAmount": 0.3,
      "walletAddress": "0x535ebf73d0E20db0A72509207599C816510e11C9",
      "transactionHash": [
        "Ox235ebf73d0E20db0A72509207599C816510e11C9535ebf73d0E20db0A72509207599C816510e11C9"
      ]
    }
  }
  ```

  ```Json Transfer Orders theme={null}
  {
    "createdAt": "2023-11-07T05:31:56Z",
    "eventUid": "853d470c-db91-4c6e-9724-acfccd138306",
    "eventType": "tranfer_orders.processing",
    "payload": {
      "createTime": "2023-11-07T05:31:56Z",
      "dstAmount": "10000",
      "dstChain": "fiat",
      "dstCurrency": "INR",
      "externalOrderUid": "707966cf-afc0-4577-bd42-cd79a5b6f629",
      "orderStatus": "completed",
      "orderType": "unknown",
      "orderUid": "5de57551-3272-4af5-86a4-5eeae6ccc37f",
      "payinMode": "sepa",
      "paymentStatus": "accepted",
      "payoutMode": "inr_bank_transfer",
      "srcAmount": "100",
      "srcChain": "solana",
      "srcCurrency": "USDC",
      "transactionRef": [
        "KJBDUEBDNKJSBDKUAEHVFDBAJ"
      ],
      "updateTime": "2023-11-07T05:31:56Z"
    }
  }
  ```
</CodeGroup>

## Field Descriptions

| Field                 | Type   | Description                                                                 |
| --------------------- | ------ | --------------------------------------------------------------------------- |
| `createdAt`           | string | Webhook event creation timestamp (ISO 8601)                                 |
| `eventUid`            | string | Unique webhook event identifier                                             |
| `eventType`           | string | Event type (e.g., `orders.processing`, `orders.completed`, `orders.failed`) |
| `orderUid`            | string | Unique Rampnow order identifier                                             |
| `externalOrderUid`    | string | External order reference                                                    |
| `createTime`          | string | Order creation timestamp (ISO 8601)                                         |
| `updateTime`          | string | Last update timestamp (ISO 8601)                                            |
| `partnerGeneratedUid` | string | Your internal order ID                                                      |
| `orderType`           | string | Transaction type: `buy` or `sell`                                           |
| `orderStatus`         | string | Current status: `processing`, `completed`, or `failed`                      |
| `paymentStatus`       | string | Payment settlement status                                                   |
| `paymentMode`         | string | Payment method used (e.g., `card`, `google_pay`)                            |
| `srcCurrency`         | string | Source currency code                                                        |
| `srcChain`            | string | Source blockchain or `fiat`                                                 |
| `srcAmount`           | number | Amount in source currency                                                   |
| `dstCurrency`         | string | Destination currency code                                                   |
| `dstChain`            | string | Destination blockchain or `fiat`                                            |
| `dstAmount`           | number | Amount in destination currency                                              |
| `walletAddress`       | string | Recipient wallet address                                                    |
| `walletAddressTag`    | string | Optional wallet tag/memo                                                    |
| `transactionHash`     | array  | Blockchain transaction hash(es)                                             |

## Best Practices

<AccordionGroup>
  <Accordion title="Security" icon="shield">
    * Use HTTPS endpoints only
    * Validate webhook signatures (if provided)
    * Implement rate limiting on your endpoint
    * Log all incoming webhooks for debugging
  </Accordion>

  <Accordion title="Reliability" icon="rotate">
    * Return `200 OK` quickly (process async if needed)
    * Implement idempotency using `orderUid`
    * Handle duplicate webhook deliveries gracefully
    * Set up monitoring and alerts for failures
  </Accordion>

  <Accordion title="Error Handling" icon="triangle-exclamation">
    * Always respond with status codes
    * Implement retry logic on your side if needed
    * Store failed webhooks for manual review
    * Contact support if webhooks stop arriving
  </Accordion>
</AccordionGroup>

## Testing Your Webhook

<Steps>
  <Step title="Set Up Local Endpoint">
    Run your webhook server locally on the specified port.
  </Step>

  <Step title="Use Tunneling Tool">
    Use tools like [ngrok](https://ngrok.com) to expose your local server:

    ```bash theme={null}
    ngrok http 3000
    ```
  </Step>

  <Step title="Add Tunnel URL">
    Copy the ngrok URL and add it to your Rampnow dashboard.
  </Step>

  <Step title="Create Test Order">
    Create a test order and verify your endpoint receives the webhook.
  </Step>
</Steps>

## Need Help?

If you encounter issues with webhook delivery or have questions about the payload structure, contact us at [support@rampnow.io](mailto:support@rampnow.io).