Setup your Webhooks

Overview

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

You can configure a primary webhook and an optional secondary webhook. When both are set, Fincart sends the same payload to each destination independently — useful as a backup endpoint or a second system that also needs order updates.

Webhook Setup Available from the Dashboard

You can configure your webhook settings directly from the dashboard.

1

Open the profile menu

Go to the top-right corner of the page and click the profile dropdown menu.

2

Open Webhook Details

Select Webhook Details from the menu.

3

Configure primary and optional secondary webhooks

The Webhook Details panel has two sections. Expand Primary Webhook or Secondary Webhook to edit each destination.

For each destination you can:

• Choose the HTTP method (GET, POST, or PATCH).

• Enter the Webhook URL where you want to receive order updates.

• Optionally set a Secret Token to secure requests to that destination.

The primary webhook URL is required. The secondary webhook is optional. If you add a secondary URL, it must be a valid http or https URL, and the secondary method and URL are saved together.

Click Save Settings to apply, or Delete Settings to remove the full configuration (primary and secondary).

Once saved, Fincart sends updates to every configured destination whenever an order status changes.

Each destination can use a different method, URL, and secret token. POST and PATCH requests include the JSON payload in the body. GET requests do not include a body — the destination must accept the request without one.

Primary vs secondary webhook

Setting	Primary	Secondary
Required	Yes — URL is required to save	No — leave empty if you only need one destination
HTTP method	GET, POST, or PATCH	GET, POST, or PATCH
Webhook URL	Destination that always receives updates	Optional backup or second system
Secret token	Optional Authorization header value	Optional, independent of the primary token
Payload	Same JSON payload	Same JSON payload

Fincart calls the primary destination first, then the secondary if it is configured. Each call is independent: a failure or timeout on one destination does not prevent the other from being attempted.

Webhook Payload Format

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

{
  "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,
  "invoicedAt": 1738336796675,
  "refNumber": "#1123"
}

invoiced and invoicedAt are returned only when the order is invoiced. refNumber is the order number in the merchant system (for example a Shopify order number).

Field Details

Field	Type	Description
status	string	The main order status (pending, processing, successful, unsuccessful, cancelled)
subStatus	string	The sub order status (picked up, out for delivery, problematic, etc.)
rejectionReason	string (nullable)	Reason for rejection if applicable (no answer, rejected, reschedule, etc.)
supportNote	string (nullable)	Additional notes related to the order update
trackingNumber	string	The tracking number assigned to the order
returnTrackingNumber	string (nullable)	If the order was returned and the courier generated a new tracking number, it will be provided here
statusUpdatedDate	number	The timestamp when the order status was updated
orderId	string	Order ID at Fincart System
orderNumber	string	Order Number at Fincart System
courier	string	Courier Name
courierLogo	string	Courier Logo
action	string	Order Updated when order details changed but status did not, or Order Status Changed when the order status changed.
invoiced	boolean	Present with value true when the order is invoiced in Fincart
invoicedAt	number	The timestamp when the order got invoiced
refNumber	string	Order ID at Merchant System

Order Status & Sub-Status Reference

Main Status	Sub Status	Failed Attempt Reason	Order Type
pending	duplicate		Delivery
pending	missing area		All
pending	missing tracking		All
pending	new		Delivery / Exchange
pending	ready		Return
processing	picked up		Delivery / Exchange
processing	at courier hub		All
processing	out for delivery		Delivery / Exchange
processing	out for return		Return
processing	out for exchange		Exchange
processing	failed attempt	no answer	All
processing	failed attempt	reschedule	All
processing	failed attempt	rejected	All
processing	failed attempt	out of zone	All
processing	failed attempt	action required	All
processing	failed attempt	to be returned	Delivery / Exchange
processing	returned to courier		Return
processing	exchanged & returned to courier		Exchange
successful	delivered to customer		Delivery
successful	returned to merchant		Return
successful	exchanged & returned to merchant		Exchange
unsuccessful	delivery failed & returned to merchant		Delivery
unsuccessful	return failed		Return
unsuccessful	exchange failed & returned to merchant		Exchange
unsuccessful	problematic		All
cancelled	cancelled		All

Authentication & Security

To ensure security, Fincart sends a token with every request when you configured a secret token for that destination. Validate the token for the destination that received the request before processing any data.

Example Request Headers

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

The primary webhook uses webhook_token. The secondary webhook uses secondary_webhook_token if one was saved. A destination with no token is called without an Authorization header.

Merchant's Responsibility:

1. Validate the webhook token for that destination 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 statuses you don't expect).

4. If you use a secondary webhook, treat it as a second independent receiver of the same event — make processing idempotent so duplicate deliveries do not double-apply an update.

Best Practices for Handling Webhooks

✅ Ensure every configured endpoint is available to receive real-time updates.

✅ Process webhook requests asynchronously to avoid delays.

✅ Implement logging & monitoring for webhook failures on both destinations.