Fluent Commerce Docs

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Content in this track:

Introduction to Integrations and Connections

Introduction to the Events API

End Of Track

Content in this track: Introduction to Webhooks

Essential knowledge

Authors:

Ankit Mehta, Movyn John, Cille Schliebitz, Anita Gu

Changed on:

3 Feb 2025

Overview

In this lesson, we'll look at what Webhooks are, their structure, features and some recommended practices around using Webhooks.

Key points

Introduction/Recap on what Webhooks are
Webhook Structure
Webhook Features
Types of integrations for Webhooks
Webhook best practices

WebhooksWebhooks are a useful tool for external systems in need of executing code after a specific event happens in the Fluent OMS, such as when an order is booked, a fulfilment is created, or an item is picked. Webhooks provide the ability for external systems to rely on receiving events in real-time, rather than having to poll the Fluent APIs for information.Here are some examples of Webhooks:

Order status updates hook
Email/SMS provider hook
Carrier aggregator hook

Webhook structureAll webhooks posted by the Fluent platform use the standard Event Model. This is the same as the Event API payload.Here you can see a Sample Payload for Webhooks.

1{
2"id": "b34281d0-ada4-11e9-a1a7-5da7a83b9sd97cd" ,
3"name": "OrderStatusChange"
4"accountId": "ACME",
5"retailerId": "1",
6"rootEntityId": "123",
7"rootEntityRef": "0_123",
8"rootEntityType" : "ORDER",
9"entityId": "123"
10"entityRef": "0_123",
11"entityType": "ORDER",
12"entityStatus": "SHIPPED",
13"type": "NORMAL"
14"attributes": {
15    "ShippingPartner": "Awesome Shipping Co."
16    "TrackingNumber": "TRACKING123" ,
17    "TrackingURL": "http://awesomeshippingco.test/track/q=TRACKING123"
18 }
19}

Next, we look at the Default SendWebhook RuleDefault SendWebhook RuleSendWebhook is a standard rule that can be added to any ruleset in a workflow. The SendWebhook is used to post the corresponding event message to any endpoint that is specified.The rule only accepts one parameter which is the url.

1"rules" : [
2    {
3"name": "FLUENTRETAIL.base.SendWebhook",
4"props": { "url": "https://testwebhook.fluentretail.com/clicksend" }
5    }
6]

Note: The Orchestration Editor can be used to add a Rule to the Ruleset in the Workflow (as shown here), that is triggered by the specific event that needs to be captured. In this case, sending a Webhook when the order gets into AWAITING_COLLECTION status. No alt provided

Webhook RetriesAt times, the external parties may be unreachable due to connectivity issues; in these cases, if the Webhook request fails due to a connection timeout, the orchestration engine will automatically reattempt the Webhook request three times. More information about Webhook Retries (opens in a new tab).Next, we look at Webhook Signature Validation.Webhook Signature Validation-Why is a Webhook Signature needed? For security purposes, Fluent Commerce cryptographically signs each Webhook request with a private key before sending to the target endpoint.-How is the request validated? To validate if the request came from Fluent Commerce and has not been tampered with or replaced by another third party, a public key is provided so that clients can verify that the signatures match the request.-What does each request contain? Every Webhook request from the Fluent OMS contains two custom headers.

flex.signature
fluent-signature

Both headers contain a hash using the event body and the private key of the environment from which this request was generated.-What's the difference between the two headers? The difference between the two is the algorithm used to generate the hash: flex.signature uses MD5withRSA while fluent-signature uses SHA512withRSA.-How can the message be verified? Clients can use the Fluent Commerce public key (opens in a new tab) (x509 base64 encoded) to verify the message using either of the signatures based on their preferred hashing algorithm.Recommended Practice: We always recommend using lightweight Webhooks, which means including only entityId/entityRef in the Webhook payload, and letting the external systems run a GraphQL query against that entityId to extract the required fields.Common Integrations: Some common integrations that use Webhooks areWMS integration: Outbound (Fulfilment Request)-Fulfilment requests to WMS/Distribution Center are sent using lightweight webhooks.Carrier Integration: Outbound-Carrier booking, label and Manifest requests are initiated through a light weighted Webhook from Fluent OMSERP Integration: Sales order create requests to ERP are triggered through webhooksOrder/Fulfilment status Update: Order status updates to eComm are triggered through webhooksNotification Service Integration: Email / SMS notifications services are triggered through webhooks