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.

   
2. Select Webhook Details from the menu.

   
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:

{
  "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
}

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

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 will send a token with every request. Merchants should validate this token before processing any data.

Example Request Headers

{
  "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).

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.