Webhooks

A webhook is a way for Orchestrated Workflow Logic to call back to an external application, such as a notification provider, client middleware, or ERP system. The Fluent Orchestration Engine can post an event to a configured endpoint so that the third-party system can be notified or react to the provided event. For example, common webhook scenarios include order status updates and shipping notifications.

Webhooks provide the ability for external systems to rely on receiving the event in real-time rather than having to poll the Fluent APIs for information.

When To Use a Webhook

Webhooks form part of the integration patterns provided by the Fluent Platform, and should be used when appropriate.

Standard Webhooks

Fluent Commerce provides some standard webhooks as Rules within the Rule Library for common third-party integrations.

• SendWebhook Rule - see below.
• Email provider hook
• SMS provider hook
• Carrier aggregator hook
• Courier hook

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{
2    "rules": [
3        {
4            "name": "FLUENTRETAIL.base.SendWebhook",
5            "props": { "url": "https://testwebhook.fluentretail.com/clicksend" }
6        }
7    ]
8}

The Orchestration Editor can be used to add the rule to the Ruleset in the workflow that is triggered by the specific event that needs to be captured:

Custom Webhooks

Since the payload and HTTP request cannot be customised, it is rarely necessary to implement a custom rule to send a webhook. Rather, the recommended approach is to add a Ruleset to your workflow, naming the specific webhook action required, and simply add the SendWebhook rule to that Ruleset, configured with the target URL. This will take the event received by the Ruleset and post it to the target URL.

Should you wish to enforce more validation on the Event interface for a particular webhook, you can add rules that define required Event Attributes to be present prior to executing the webhook rule itself.

Example Ruleset:

Should you wish to perform any additional custom logic not available with composition of existing rules, you may wish to build your own webhook rule using the Fluent SDK, and creating a custom plugin. The custom webhook rule will have access to an Action called `postWebhook`.

For information on Fluent SDK, please check out the pages below.

• SDK Installation Steps
• Sample Rule Plugin

Custom Webhook rule failure logic

By default, when a Webhook in a custom Rule fails it reverts back to the default Webhook action logic. To prevent this and use the logic set up in the custom Rule, add the following Setting to any Workflow containing a custom Webhook.

`    "settings": {"fc.rubix.sdk.webhook.retry.method":"preserve-event-details"}`

Learn more about adding settings to a Workflow.

Webhook Sample payload

All webhooks posted by the Fluent platform use the standard Event Model. This is the same as the Event API payload. More information can be found under Event API

The following is a sample payload for a webhook:

1{
2    "id": "b34281d0-ada4-11e9-a1a7-5da7a83b9sd97cd",
3    "name": "OrderStatusChange",
4    "accountId": "ACME",
5    "retailerId": "1",
6    "rootEntityId": "123",
7    "rootEntityRef": "O_123",
8    "rootEntityType": "ORDER",
9    "entityId": "123",
10    "entityRef": "O_123",
11    "entityType": "ORDER",
12    "entityStatus": "SHIPPED",
13    "type": "NORMAL"
14}

Webhook Retries

There are two options for retry schedules, Exponential Back-off and 2 Second Intervals.

Option A: Exponential Back-off (recommended)

If the Webhook request fails due to a connection timeout, the Workflow Engine will automatically reattempt the Webhook request four times.

The "Retry Delay" for every retry is as follows:

• Immediate: for random errors
• 1 minute: for short-term issues like rate limiting
• 1 hour: for scheduled downtimes
• 1 day: for production outages on the target environment

How to enable Exponential Back-off

To enable Exponential Back-off, add the following setting to the Settings Object in your Workflow:

`"settings": {"fc.rubix.sdk.webhook.retry.schedule":"exponential"}`

To learn how to enable Workflow Settings like this, see the adding a setting to a Workflow guide.

To learn more about available settings, see the Workflow Settings page.

Option B: 2 Second Intervals 

If the Webhook request fails due to a connection timeout, the Workflow Engine will automatically reattempt the Webhook request three times.

The "Retry Delay" for every retry is calculated using the Retry Fallback Formula as below:

• Retry delay for 1st retry = [Math.pow(2, 0) * 2] = 2 seconds
• Retry delay for 2nd retry = [Math.pow(2, 1) * 2] = 4 second
• Retry delay for 3rd retry = [Math.pow(2, 2) * 2] = 8 seconds

Total Retry Delay after all 3 retries = 2 + 4 + 8 = 14 seconds.

How to enable 2 Second Intervals 

This option is set as default and does not need to be enabled.

Webhook id

The event that is sent as part of the webhook requires the id field to ensure that the webhook retries are executed correctly. For example, the following code has randomUUID set as id.

1Event event = Event.builder() 
2    .id(UUID.randomUUID()) //REQUIRED 
3    .name(action) 
4    .accountId(incomingEvent.getAccountId())         
5    .retailerId(incomingEvent.getRetailerId()) 
6    .entityId(invoiceId) 
7    .entityRef(invoiceRef)
8    .entityType(incomingEvent.getEntityType())
9    .attributes(attributes)
10    .build();
11
12context.action().postWebhook(webhookEndpoint, event);

Webhook Exceptions

If the Webhook request fails more than the maximum amount of failures based on the chosen retry schedule, it will audit a `RetriesExceededException`, and create an event named `<RuleName> Exception`. This event can be used to execute a custom Ruleset in your workflow to act on this issue, such as sending an email or SMS notification.

Non-retry-able Webhook Exceptions

If the Webhook Action failed due to an issue in generating the digital signature for the request, then it will not retry since this is not considered a transient exception. Instead, this will be audited as an `ActionException` in the orchestration audit events.

For more info on Webhook Signing, see Signature Validation.