# 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.


---

# 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://fincart.gitbook.io/fincart-api/webhooks/setup-your-webhook.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.