Callout Plugin (Synchronous Webhooks)
Overview
The Callout Plugin allows real-time communication with external systems during order processing. It sends a JSON payload of the Limio order object (schema) to a specified endpoint and processes the response before proceeding to the next plugin.
When set to critical, the plugin is synchronous — order processing is blocked until the callout completes. This ensures external systems have processed the data before billing or other downstream steps proceed.
If you don't need synchronous processing, use asynchronous webhooks instead, which fire when the order is created (regardless of plugin success or failure).
How It Works
The Callout Plugin sends a POST request to the configured endpoint with the full Limio order payload.
The external system processes the request and returns a response.
The response (including body, status, and headers) is stored as a callout record linked to the process event.
If the response status matches a rejection code, the order fails (if the plugin is critical).
Subsequent plugins in the sequence can read the callout response from the process event to use data returned by the external system.
Configuration
{
"name": "calloutPlugin",
"service": "limio",
"critical": true,
"options": {
"endpoint": "https://example.com/api/provision",
"timeoutValue": 5000,
"shouldRejectOn": {
"status": [400, 404, 500]
}
}
}Configuration Options
endpoint
string
Required
The URL to send the order payload to.
timeoutValue
number
2000
Timeout in milliseconds. If no response is received within this time, the plugin fails.
shouldRejectOn.status
number[]
[]
HTTP status codes that should trigger a failure. If the response status matches any code in this array, the plugin throws an error.
Authentication
The Callout Plugin supports Basic Authentication. If you have configured an auth provider in Limio's General Settings for the endpoint's domain, the plugin will automatically include an Authorization header with the credentials.
Contact [email protected] to configure authentication for your callout endpoint.
Multiple Callouts
You can include multiple Callout Plugins in the same sequence, each configured with a different endpoint. For example, you might call an account provisioning system first, then a fulfilment validation service second.
Response Handling
Success: The order processing continues to the next plugin.
Failure (rejection): If the response status matches a code in
shouldRejectOn.status, processing halts (when the plugin is critical). Example error:callout plugin failed due to response status: [404]Timeout: If no response is received within
timeoutValuemilliseconds, the plugin fails. Example error:This operation was aborted
How Callout Responses Are Used
Callout responses are stored as records linked to the order's process event. Subsequent plugins in the orchestration sequence can query these records to extract data from the external system's response.
For example, if the external system returns a unique identifier in its response body, a downstream plugin can read that identifier and use it when creating a billing account. This enables cross-system data flow within a single order processing pipeline.
Example Use Cases
1. Account Provisioning
A common pattern is to provision a user or account in an external system before creating the corresponding billing record.
Sequence:
How it works:
Customer submits an order.
The Callout Plugin sends the order payload to the provisioning API.
The API creates a user/account and returns a unique identifier (e.g.,
{"accountId": "ACC-12345"}).This response is stored in the process event.
The Zuora plugin reads the stored response and uses the identifier as the billing account number, ensuring cross-system consistency.
After order completion, an async webhook notifies the external system that billing is active.
2. Fulfilment Validation
Validate whether an order can be fulfilled before processing payment.
Sequence:
How it works:
Customer submits an order with a delivery address.
Salesforce records are created.
The Callout Plugin sends the order (including address) to the fulfilment partner's API.
The fulfilment partner validates the address and confirms deliverability.
If the partner returns a rejection status (e.g.,
400), the order fails with an error message before payment is taken.If successful, the Zuora plugin proceeds with billing.
Configuration for this use case:
3. Entitlement Activation
Activate user access in an external entitlement system as part of order processing, ensuring the customer is entitled before the order completes.
Sequence:
How it works:
Payment is processed via Zuora.
The Callout Plugin sends the order to the entitlement system.
The entitlement system provisions access and returns a confirmation.
If the entitlement system fails, the order is marked as failed — this allows the operational team to investigate and manually resolve.
4. Non-Critical Data Enrichment
Send order data to a third-party system for analytics or enrichment without blocking the order.
When critical is set to false, the order continues even if the callout fails. The failure is still logged in the process event for visibility.
Callout Plugin vs Async Webhooks
Timing
During order processing
After order processing completes
Blocking
Yes — processing waits for response
No — fire and forget
Can reject orders
Yes (when critical)
No
Response stored
Yes — available to subsequent plugins
N/A
Use case
Provisioning, validation, enrichment
Notifications, data sync, analytics
Learn more about async webhooks in Webhooks and Notifications.
Troubleshooting
Callout execution details (endpoint, timing, request/response payloads) are recorded in the process event. See Troubleshooting Order Processing for how to inspect callouts.
Last updated
Was this helpful?