> For the complete documentation index, see [llms.txt](https://fincart.gitbook.io/fincart-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fincart.gitbook.io/fincart-api/webhooks/setup-your-webhook.md).

# Setup your Webhook

**Overview**

Fincart now supports **Webhook Notifications** to **automatically update merchants' systems** whenever an order status changes.This allows merchants to receive **real-time order status updates**, eliminating the need for polling APIs and ensuring their system is always in sync.

#### Webhook Setup  Available from the Dashboard

You can  configure your webhook settings directly from the dashboard.

1. Go to the **top-right corner** of the page and click the **profile dropdown menu**.<br>

   <figure><img src="/files/tJNORhNWPeJvO0YMli8q" alt=""><figcaption></figcaption></figure>
2. Select **Webhook Details** from the menu.<br>

   <figure><img src="/files/qTNMLzWmQaryWPLlZAfI" alt=""><figcaption></figcaption></figure>
3. In the Webhook Details panel, you can:
   * Choose the **HTTP method** (e.g., POST).
   * Enter your **Webhook URL** where you want to receive order updates.
   * Optionally, set a **Secret Token** to secure your webhook requests.

Click **Save Settings** to apply or **Delete Settings** to remove the configuration.

Once saved, Fincart will automatically send updates to your system whenever an order status changed.

**Webhook Payload Format**

When an order status update occurs, Fincart will send an HTTP request to the configured webhook URL with the following JSON payload:

```json
{
  "status": "processing",
  "subStatus": "out for delivery",
  "rejectionReason": null,
  "supportNote": "Customer requested a delay",
  "trackingNumber": "ARX123456XXX",
  "returnTrackingNumber": null,
  "statusUpdatedDate": 1738336796675, 
  "orderId": "67387ce18aa2230090e0XXXX", 
  "orderNumber": "ZZZ-DR-0013XXX",
  "courier": "J&T", 
  "courierLogo": "logo",
  "action": "Order Updated", 
  "invoiced": true,  //Optional Field, will return only if order is invoiced
  "invoicedAt": 1738336796675, //Optional Field, will return only if order is invoiced
  "refNumber": "#1123" //Order number at customer system , like Shopify Order Number
}
```

&#x20;**Field Details**

<table><thead><tr><th width="221.86383056640625">Field</th><th width="148.5902099609375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td><code>string</code></td><td>The main order status (<code>pending</code>, <code>processing</code>, <code>successful</code>, <code>unsuccessful</code>, <code>cancelled</code>)</td></tr><tr><td><code>subStatus</code></td><td><code>string</code></td><td>The sub order status (<code>picked up</code>, <code>out for delivery</code>, <code>problematic</code>, etc.)</td></tr><tr><td><code>rejectionReason</code></td><td><code>string</code> (nullable)</td><td>Reason for rejection if applicable (<code>no answer</code>, <code>rejected</code>, <code>reschedule</code>, etc.)</td></tr><tr><td><code>supportNote</code></td><td><code>string</code> (nullable)</td><td>Additional notes related to the order update</td></tr><tr><td><code>trackingNumber</code></td><td><code>string</code></td><td>The tracking number assigned to the order</td></tr><tr><td><code>returnTrackingNumber</code></td><td><code>string</code> (nullable)</td><td>If the order was returned and the courier generated a new tracking number, it will be provided here</td></tr><tr><td><code>statusUpdatedDate</code></td><td><code>number</code></td><td>The timestamp when the order status was updated</td></tr><tr><td><code>orderId</code></td><td><code>string</code></td><td>Order ID at Fincart System</td></tr><tr><td><code>orderNumber</code></td><td><code>string</code></td><td>Order Number at Fincart System</td></tr><tr><td><code>courier</code></td><td><code>string</code></td><td>Courier Name</td></tr><tr><td><code>courierLogo</code></td><td><code>string</code></td><td>Courier Logo</td></tr><tr><td><code>action</code></td><td><code>string</code></td><td>"Order Updated" In case order details changed but status didn't change, or "Order Status Changed" in case order status has been changed. </td></tr><tr><td><code>invoiced</code></td><td><code>boolean</code></td><td>If order got invocied at Fincart System your will get this field with true value</td></tr><tr><td><code>invoicedAt</code></td><td><code>number</code></td><td>The timestamp when the order got invoiced</td></tr><tr><td><code>refNumber</code></td><td><code>string</code></td><td>Order ID at Merchant System</td></tr></tbody></table>

#### **Order Status & Sub-Status Reference**

<table><thead><tr><th width="164">Main Status</th><th width="302.17291259765625">Sub Status</th><th>Failed Attempt Reason</th><th>Order Type</th></tr></thead><tbody><tr><td><code>pending</code></td><td><code>duplicate</code></td><td></td><td>Delivery</td></tr><tr><td><code>pending</code></td><td><code>missing area</code></td><td></td><td>All</td></tr><tr><td><code>pending</code></td><td><code>missing tracking</code></td><td></td><td>All</td></tr><tr><td><code>pending</code></td><td><code>new</code></td><td></td><td>Delivery / Exchange</td></tr><tr><td><code>pending</code></td><td><code>ready</code></td><td></td><td>Return</td></tr><tr><td><code>processing</code></td><td><code>picked up</code></td><td></td><td>Delivery / Exchange</td></tr><tr><td><code>processing</code></td><td><code>at courier hub</code></td><td></td><td>All</td></tr><tr><td><code>processing</code></td><td><code>out for delivery</code></td><td></td><td>Delivery / Exchange</td></tr><tr><td><code>processing</code></td><td><code>out for return</code></td><td></td><td>Return</td></tr><tr><td><code>processing</code></td><td><code>out for exchange</code></td><td></td><td>Exchange</td></tr><tr><td><code>processing</code></td><td><code>failed attempt</code></td><td><code>no answer</code></td><td>All</td></tr><tr><td><code>processing</code></td><td><code>failed attempt</code></td><td><code>reschedule</code></td><td>All</td></tr><tr><td><code>processing</code></td><td><code>failed attempt</code></td><td><code>rejected</code></td><td>All</td></tr><tr><td><code>processing</code></td><td><code>failed attempt</code></td><td><code>out of zone</code></td><td>All</td></tr><tr><td><code>processing</code></td><td><code>failed attempt</code></td><td><code>action required</code></td><td>All</td></tr><tr><td><code>processing</code></td><td><code>failed attempt</code></td><td><code>to be returned</code></td><td>Delivery / Exchange</td></tr><tr><td><code>processing</code></td><td><code>returned to courier</code></td><td></td><td>Return</td></tr><tr><td><code>processing</code></td><td><code>exchanged &#x26; returned to courier</code></td><td></td><td>Exchange</td></tr><tr><td><code>successful</code></td><td><code>delivered to customer</code></td><td></td><td>Delivery</td></tr><tr><td><code>successful</code></td><td><code>returned to merchant</code></td><td></td><td>Return</td></tr><tr><td><code>successful</code></td><td><code>exchanged &#x26; returned to merchant</code></td><td></td><td>Exchange</td></tr><tr><td><code>unsuccessful</code></td><td><code>delivery failed &#x26; returned to merchant</code></td><td></td><td>Delivery</td></tr><tr><td><code>unsuccessful</code></td><td><code>return failed</code></td><td></td><td>Return</td></tr><tr><td><code>unsuccessful</code></td><td><code>exchange failed &#x26; returned to merchant</code></td><td></td><td>Exchange</td></tr><tr><td><code>unsuccessful</code></td><td><code>problematic</code></td><td></td><td>All</td></tr><tr><td><code>cancelled</code></td><td><code>cancelled</code></td><td></td><td>All</td></tr></tbody></table>

**Authentication & Security**

To ensure security, Fincart will send a **token** with every request. Merchants should validate this token before processing any data.

**Example Request Headers**

```json
{
  "Authorization": "{webhookToken}",
  "Content-Type": "application/json"
}
```

**Merchant’s Responsibility:**

1. **Validate the webhookToken** before processing the request.
2. **Store the status updates** in your system.
3. **Handle failures gracefully** (e.g., retry logic for failed requests, ignore fields and status you don't expect).

#### **Best Practices for Handling Webhooks**

✅ **Ensure your endpoint is always available** to receive real-time updates.

✅ **Process webhook requests asynchronously** to avoid delays.

✅ **Implement logging & monitoring** for webhook failures.