Flow Notifier Webhook Format

Created by Brian Glick, Modified on Tue, 4 Nov at 12:58 PM by Brian Glick

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.

Learn more about notifiers here.

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.