Listening to Delivery Events

Webhooks allow extensions to stay in sync with the Fynd Commerce data or perform actions after a specific event occurs in a store. Webhooks are a performant alternative to continuously polling for changes to store data.

Reference

Refer to Webhooks for the full list of available webhook events and configuration details.

Register for Webhook Events

A POST API path on the given api_path to receive webhook call. The API must call the fdkExtension.webhookRegistry.processWebhook() method with the request object. This method validates the payload with a signature and calls individual handlers for the event passed in the webhook config.

const fdkExtension = setupFdk({ ... });

app.post('/api/webhooks', async (req, res, next) => {
  try {
    await fdkExtension.webhookRegistry.processWebhook(req);
    return res.status(200).json({"success": true});
  }
  catch(err) {
    logger.error(err);
    return res.status(500).json({"success": false});
  }
});

Webhook events help you handle tasks when certain events occur on the platform. You can subscribe to such events by passing webhook_config in the setupFdk function. After the webhook_config is passed to setupFdk, whenever an extension is installed or to be installed, webhook config data is used to create a webhook subscriber on the Fynd Commerce for the company where the extension is launched. Any update to the webhook config will not automatically update subscriber data on Fynd Commerce for a company until the extension is opened at least once after the update.

    webhook_config: {
        api_path: "/api/webhook-events",
        notification_email: "abc@gofynd.com",
        event_map: {
            },
            'application/courier-partner/assign': {
                handler: webhookHandler.courierPartnerAsign,
                version: '1',
            },
            'application/courier-partner/cancel': {
                handler: webhookHandler.courierPartnerCancel,
                version: '1',
            }
        }
    },

When a new logistics extension is added, it is required to configure it to receive the messages (Assign shipment and Cancel shipment). Whenever the OMS sends any of this message, it includes two important IDs: Extension ID and Scheme ID. To ensure the extension receives the correct messages, it is required to set up and configure a webhook to subscribe to the relevant events.

Assign Shipment Event

This event is triggered when a DP is ready to be assigned. The OMS emits an Assign DP event to the respective DP extension after invoice is generated and DP acknowledges it by sending dp_assigned status. This event specifies various shipment variations, such as Forward, Reverse, Multi-Piece Shipments (MPS), COD/Prepaid, and whether Quality Check (QC) is required.

• MPS
  • A Multi-Piece Shipment (MPS) involves multiple packages being shipped together under a single tracking number, ensuring that all packages in the shipment are processed and delivered together. This method is often used for large orders that are split into several parcels but are meant to be delivered to the same destination at the same time under same shipment id or parent AWB
• Doorstep QC
  • Doorstep Quality Check (QC) is a service where the quality of the to-be-picked up items is verified at the customer's doorstep before accepting the return. This ensures that the products meet the expected standards and allows for immediate returns or exchanges if any issues are detected.
• COD
  • Indicates that the shipment is a COD order and needs to collect payment amount from the customer while delivering the shipment
• EWay Bill
  • An e-way bill is required during the transportation of goods valued above ₹50,000 in India, either interstate or intrastate, to ensure compliance with GST regulations. It helps prevent tax evasion by providing a digital record of goods being transported, thus facilitating easier tracking and verification by authorities.
• QR
  • A QR code on an invoice is required for businesses with an annual turnover above ₹500 crores in India, as per GST regulations. It ensures the easy digital verification of the invoice, enhances transparency, and speeds up processing for compliance and audit purposes.

API: application/courier-partner/assign/

Example Snippets

async function courierPartnerAsignHandler(event_name, request_body, company_id, application_id) {
    console.log(JSON.stringify(request_body));
    console.log(event_name);
    console.log(company_id);
    console.log(application_id);
}

Cancel Shipment Event

This event is triggered when DP cancels the shipment. If the seller or end-customer cancels the shipment, the OMS sends a Cancel DP event.

API: application/courier-partner/cancel/

Example

async function courierPartnerCancelHandler(event_name, request_body, company_id, application_id) {
    console.log(JSON.stringify(request_body));
    console.log(event_name);
    console.log(company_id);
    console.log(application_id);
}