You can receive webhook each time a flow completes. These webhooks contain details about the final state of the flow including messages and data tags.
Webhook Limits
The feature to add webhooks to flows is limited to workspaces with either Transform or Enterprise licenses. For more information about our licenses: chain.io/product/pricing
Subscribe to Webhooks
You can subscribe to webhooks for successful flows, failed flows or both. You can use this feature to do the following:
- Showing the status of integrations to users within your application
- Opening internal help desk tickets for failures
- Retrieving attribute data from data tags generated by your trading partner's adapter
Configuring Your Webhook
You can add a webhook to any flow at the bottom of the flow configuration screen.
- Under the Notifications tab, Click the green + button to add a new webhook.
- Enter the address where you would like the webhook to be delivered.
- Optionally: Enter an API Key that you would like the webhook to include as an "x-api-key" header on every request to your server
- Check the Success, Skip, Fail checkboxes to receive webhooks for successful flows, failed flows, skipped flows, or all.
- Don't forget to save the flow before leaving the screen.
Webhook Structure
Webhooks will be sent to your server as a POST with JSON body content.
Sample Body
{
"finish_date": "2021-09-22T22:13:27.973Z",
"flow_status": "logical_fail",
"flow_uuid": "5b288b82-c965-4497-ba78-6b9f9581d014",
"start_date": "2021-09-11T21:37:25.774Z",
"additional_data_events": [
{
"reason_code": "EUF",
"message": "Server rejected. Unknown customer number.",
"attributes": []
}
],
"flow_name": "JSON Shipments to My Host System",
"invocation_uuid": "626e8771-5d25-4b50-b167-82dc2fdb7105",
"organization_uuid": "f85b5ead-092f-445b-99c3-44abe9059f48",
"partner_uuid": "f80e09d4-d7d6-4c28-a0e7-8c9c2a76a082",
"summary_message": "Upload failed using HTTPs Transmit Adaptor",
"data_tags": [
{
"label": "Master Bill",
"value": "MBOL12345"
},
{
"label": "Host System UUID",
"value": "1391841kf813201"
}
],
"portal_url": "https://red-portal.chain.io/c/f85b5ead-092f-445b-99c3-44abe9059f48/tp/f80e09d4-d7d6-4c28-a0e7-8c9c2a76a082/f/626e8771-5d25-4b50-b167-82dc2fdb7105"
}
Fields
| Field | Description |
|---|---|
additional_data_events |
An array of events generated by the flow adapters. Events will have at least reason_code and message. Reason codes are specific to each flow adapter. |
data_tags |
An array of tags generated by the adapters with "label" and "value" attributes |
finish_date |
ISO8601 timestamp of the time that the flow finished executing |
flow_name |
The name provided on the flow setup screen |
flow_status |
The final status of the flow. See flow statuses below for details. |
flow_uuid |
The identifier for the flow configuration which will be consistent across multiple invocations of the flow |
invocation_uuid |
A unique identifier for this individual execution of the flow |
organization_uuid |
The identifier for the organization that owns the flow |
partner_uuid |
The identifier for the trading partner configured for the flow |
portal_url |
A hyperlink to the flow invocation in the Chain.io portal |
summary_message |
A short summary message related to the completion of the flow |
start_date |
ISO8601 timestamp of the time that the flow started executing |
Flow Statuses
- Success - The flow completed successfully.
- Skipped - The flow did not meet execution criteria at a step and intentionally stopped execution.
- Technical errors - The flow stopped execution because it met a data quality issue or issue with an external system. Technical errors are not monitored by the Chain.io helpdesk and should be resolved by you or your trading partner.
- Error - The flow failed unexpectedly.
If you subscribe for success webhooks, you'll receive success & skipped statuses. If you subscribe for fail webhooks you'll receive both technical errors & errors webhooks.