Introduction to Webhooks

Webhooks

Webhooks 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 structure

All 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 Rule

Default SendWebhook Rule

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

Webhook Retries

At 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 are

WMS 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 OMS

ERP Integration: Sales order create requests to ERP are triggered through webhooks

Order/Fulfilment status Update: Order status updates to eComm are triggered through webhooks

Notification Service Integration: Email / SMS notifications services are triggered through webhooks