Webhooks

Essential knowledge

Intended Audience:

Technical User

Authors:

Fluent Commerce, Kirill Gaiduk

Changed on:

5 Nov 2026

Overview

Fluent Commerce can post reference webhooks 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.

Key points

A webhook is a way for Orchestrated Workflow Logic to call back to an external application.
Fluent Commerce provides standard rules in the Rule Library that send webhooks for common third-party integrations.
Since the payload and HTTP request cannot be customized, it is rarely necessary to implement a custom rule to send a webhook

Note

Only standard webhook ports 80 and 443 are supported.

What is a Webhook?

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.

Use Case	Webhook?	Event API?	Examples
Real-time Updates	✅	❌	Webhooks are perfect for individual orchestrated changes such as Order Status Updates, Shipping Notifications, etc.
Bulk / High Load Batch Orchestration	❌	✅	Webhooks must NOT be used under high-load bulk orchestrations such as Inventory Batches. If required, the Event API may be used to query for information.
Polling	❌	Rarely	Webhooks should not be used to poll any third party or external system, ever! We do not recommend polling the Fluent Platform via the Event API; however, if required, this should be done as optimally as possible and not too frequently.

Reference Webhooks

Fluent Commerce provides some reference 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

Reference SendWebhook Rule

`SendWebhook` is a reference 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 accepts one parameter, `setting` - the name of the Setting that holds the webhook endpoint configuration.

1{
2    "rules": [
3        {
4            "name": "[[account.id]].core.SendWebhook",
5            "props": { 
6                "setting": "webhook.payment.capture"
7            }
8        }
9    ]
10}

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: No alt provided

Custom Webhooks

The reference `SendWebhook` rule covers most cases, so a custom webhook rule is rarely needed. 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 setting that holds the webhook endpoint. 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:

SendOrderStatusUpdateToEcom

ValidateEventAttribute

SendWebhook

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.

Custom Webhook Rule Failure Logic

By default, when the webhook action of a custom rule fails, the retry is sent by the built-in platform rule `FLUENTRETAIL.base.SendWebhook`, without the logic of the custom rule.To rerun the custom rule instead, add the following setting to every workflow that contains a custom webhook rule:
`"settings": {"fc.rubix.sdk.webhook.retry.method":"preserve-event-details"}`

With `preserve-event-details`, the rule that produced the webhook action runs again on each retry, with its props. See `fc.rubix.sdk.webhook.retry.method`
The retry event that triggers the rule again is built from the webhook event with `webhook-event`, or from the initial event of the event context with `initial-event`. See `fc.rubix.webhook.retry.event`
Add the setting also to workflows that use the reference `SendWebhook` rule. The rule posts the event under the name from its webhook setting, and without `preserve-event-details` the retry is posted under the name of the retry event

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}

Note

Additional attributes can be sent as part of a Webhook, however, we recommend a lightweight Webhook approach for the following reasons:

avoid stale data - if the booking takes some time to process (say, because the carrier API is down for maintenance) and the customer happens to change their address details in the meantime, the old address isn't baked into the payload
simplicity of updates - if the carrier API updates and now requires more information, rather than having to update both the rule and the connector to send the additional parts, only the connector needs to be updated to fetch them.

Instead of sending data with the Webhook body, the Webhook should just notify your external system. If the system needs data it should use the Fluent Platform APIs to retrieve what they need.For example, instead of booking a shipment in an external shipping platform with a Webhook call containing all the shipping information, have your Webhook notify the external shipping platform of the booking and task it use Fluent APIs to retrieve shipment details.

HTTP Response Code Handling

Understanding how the Fluent Platform handles HTTP response codes from your webhook endpoint is critical for designing reliable integrations.

Recommendation: Always Return HTTP 200

Your webhook endpoint should always return a 200 OK response for successfully received webhooks.Returning any other 2xx code (including 202 Accepted) or non-2xx code has specific platform implications described below. Design your endpoint to acknowledge receipt with a 200 immediately, then process the payload asynchronously.

HTTP Code	Meaning	Platform Behavior
200 OK	Success (recommended)	Webhook delivery recorded as successful. Response body, headers, response code, and reason are all saved to the orchestration audit log.
202 Accepted	Async acknowledgement	Treated as an asynchronous webhook acknowledgement. The platform does not save the response body, response headers, response code, or response reason. This is by design.
4xx Client Error	Client-side failure	Recorded as delivered. The Send Webhook audit event has the `SUCCESS` status and the response code. No automatic retries are attempted. Monitor using the Event API for Send Webhook audit events and check for non-200 responses.
5xx Server Error	Server-side failure	Recorded as delivered. The Send Webhook audit event has the `SUCCESS` status and the response code. No automatic retries are attempted. Use the Event API or entity status monitoring to detect and manually retry failed deliveries.

Retries are treated the same way. If the receiving system responds to a retry with any HTTP status code, the retry is recorded as delivered and no further retries are attempted.

Monitoring Non-200 Responses

Since 4xx and 5xx responses do not trigger automatic retries, proactive monitoring is essential. Two approaches are available:

Option A: Event API Monitoring

Poll the Event API for `Send Webhook` audit events and identify any that return responses other than `200` by parsing the JSON (see this sample JSON non-`200` response):

`curl --location 'https://{{accountId}}.sandbox.api.fluentretail.com/api/v4.1/event?eventType=ORCHESTRATION_AUDIT&name=Send%20Webhook&category=ACTION&from={{fromDateTime}}&to={{toDateTime}}' --header 'Authorization: bearer {{token}}' --header 'Accept: */*'`

Option B: Entity Status Monitoring

Monitor periodically entities stuck in a particular status in their lifecycle for longer than they should be. Check this topic on setting up business monitoring. Once a failed webhook has been identified by one of the above methods, then it can be retried manually using this approach: Manual Event with Run-Once Workflow.

Webhook Retries

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

Option A: Exponential Back-off (Recommended)

Error / Exception Type	Retries	Connection Timeout	Read Timeout	Retry Interval	Retry Fallback Schedule	Retry Max Attempts
Network error (connect or read timeout, connection refused, DNS, TLS)	✅	10 seconds	10 seconds	Exponential	Immediate, 1 minute, 1 hour, 1 day	4
HTTP 4xx	❌	-	-	-	-	-
HTTP 5xx	❌	-	-	-	-	-
All others	❌	-	-	-	-	-

If the Webhook request fails due to a network error, such as a connection or read 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

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

Error / Exception Type	Retries	Connection Timeout	Read Timeout	Retry Interval	Retry Fallback Formula	Retry Max Attempts
Network error (connect or read timeout, connection refused, DNS, TLS)	✅	10 seconds	10 seconds	2 seconds	`Math.pow(2, previousRetriesAmount) * retryInterval`	3
HTTP 4xx	❌	-	-	-	-	-
HTTP 5xx	❌	-	-	-	-	-
All others	❌	-	-	-	-	-

If the Webhook request fails due to a network error, such as a connection or read 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 seconds
Retry delay for 3rd retry = [Math.pow(2, 2) * 2] = 8 seconds

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

Enable 2 Second Intervals

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

Retry Event

By default, a failed webhook is retried with the webhook event, which is the event that triggered the ruleset in which the webhook action was produced. The retry has the name, entity, and attributes of that event, so it repeats the original call. Only the webhook is sent again. The other rules of the ruleset aren’t run again.This also applies when the webhook event is an inline event.

Existing Accounts

Accounts created before the setting was introduced have `fc.rubix.webhook.retry.event` set to `initial-event`. On these accounts, a webhook reached through inline events is retried with the initial event. If the receiving system responds, the retry counts as delivered, the original call isn’t sent again, and the failure goes unnoticed.To decide whether to switch to `webhook-event`, see Webhook Retries and Inline Events.

Webhook id

In a custom webhook rule, set the `id` field of the event that is sent as part of the webhook, so that the receiving system can identify each call and recognize a call it has already received. 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 all retries of the chosen retry schedule fail, the Orchestration Engine audits a `RetriesExceededException` and creates an event named `<RulesetName> Exception` for the ruleset and entity of the retry event. This is the webhook event by default, or the initial event with `initial-event`. Use this event to trigger a custom ruleset in your workflow that acts on the failure, such as sending an email or SMS notification. Add triggers for every status that the entity can be in when the final retry fails.

Note

Exceptions from webhook actions aren’t returned to the rule that produced the action. Webhook actions are queued and executed after all rulesets of the event context have run.

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.

Webhooks

Overview

Key points

What is a Webhook?

When To Use a Webhook?

Reference Webhooks

Reference SendWebhook Rule

Custom Webhooks

Custom Webhook Rule Failure Logic

Webhook Sample Payload

HTTP Response Code Handling

Monitoring Non-200 Responses

Option A: Event API Monitoring

Option B: Entity Status Monitoring

Webhook Retries

Option A: Exponential Back-off (Recommended)

Option B: 2 Second Intervals

Retry Event

Webhook id

Webhook Exceptions

Non-retry-able Webhook Exceptions

Related content

GraphQL API Error Message and Webhooks Enhancements 2020-03-06

New exponential backoff schedule for failed Webhook retry

fc.rubix.sdk.webhook.retry.method

fc.rubix.webhook.retry.event

Webhook Retries and Inline Events

Fluent Commerce

Contributors:

Knowledge Tracks Related To This Topic

Building Blocks

By Type

Helpful Resources

Quick Links