API Reference

Webhook Sent To Your Adapter

Request from Chain.io

When a Flow Execution invokes your adapter, it will send an HTTP POST request to the webhook_url that was designated when creating the adapter via the Create Adapter endpoint.

See the Chain.io OpenAPI file's RemoteAdapterRequest schema for a full technical overview of the HTTP request sent to the adapter.

The basic structure of the HTTP POST body will be as follows:

{
  "configuration": {
    // one key for each configuration object you created when you registered the adapter
    "exampleBoolean": true,
    "exampleTable": [
      { "src": "OCEAN", "dest": "SEA" },
      { "src": "TRUCK", "dest": "ROAD" }
    ],
    "exampleString": "somevalue"
  },
  // For output converters, the payload will represent the flow solution data appropriate
  // for the flow type the adapter is registered against
  // For input converters, the payload will represent the raw input files that were sent 
  // to the flow.
  "payload": {},
  // a callback string that you MUST include in your response body without modification
  "callback": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Y2E1YzAyMC01OTE5LTQwMGEtODQ2Zi1mZmIzZWJmMGE1MTIiLCJpYXQiOjE2ODA3MjE1NjIsImV4cCI6MTY4MDcyNTE2Mn0.sVwCFavOQf2ZpOD1SNtgjSD0Yc2mntRYUAzeRA8Iavo"
}

Input Adapter Request

If you are working with an input adapter type, the payload will represent the files that were input into the flow. An example of the HTTP body sent to an input adapter type is as follows:

{
  "configuration": {
    "configOne": "value"
  },
  "payload": [
    {
      "file_name": "example.json",
      "mime_type": "application/json",
      "body": "{\"doc_type\":\"shipment_json\",\"shipments\":[{\"forwarder_reference\":\"8901238901\",\"gross_weight_kgs\":1000}]}",
      "content_transfer_encoding": "utf8"
    }
  ],
  // a callback string that you MUST include in your response body without modification
  "callback": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Y2E1YzAyMC01OTE5LTQwMGEtODQ2Zi1mZmIzZWJmMGE1NTUiLCJpYXQiOjE2ODA3MjE1NjIsImV4cCI6MTY4MDcyNTE2Mn0.W44V0fVUShecExJ6rvZxTPZALO7v7XNCgI1JGq5nSSg"
}

Output Adapter Request

If you are working with an output adapter type, the payload will represent the data the input adapter produced. An example of the HTTP body sent to an output adapter type that is registered to the co2.register_shipment solution is as follows:

{
  "configuration": {
    "name": "value"
  },
  "payload": {
    "tms_system_identifier": "S1231231",
    "master_bill": "MOLU123181",
    "carrier_scac": "MAEU",
    "transport_mode": "sea",
    "gross_weight": {
      "amount": 1000,
      "units": "kilogram"
    }
  },
  "callback": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Y2E1YzAyMC01OTE5LTQwMGEtODQ2Zi1mZmIzZWJmMTkwMTIiLCJpYXQiOjE2ODA3MjE1NjIsImV4cCI6MTY4MDcyNTE2Mn0.XWz5D2-d3_03QMAgTs-9yqHrNiA0Pr4EF5oiWshEbJ0"
}

Request Headers

Regardless of the adapter type, Chain.io will send the following HTTP request headers:

{
  "content-type": "application/json",
  // HMAC SHA256 signature of your response body signed with the sharedSecret value you used when registering your adapter.
  "x-chainio-signature": "EUGgz5Vm0hXT9RJg41niEH+TBH2pAGrIIzBGT1zwPfw=",
  // Unique identifier for this adapter execution
  "x-chainio-execution-id": "db5f657d-f9c9-49cd-92ac-1e321f086500",
  // Identifies the workspace in the Chain.io Portal associated with this request
  "x-chainio-workspace-id": "1ed988a4-e84a-4014-b0dd-33fdc8e09579",
  // Identifiers the flow in the Chain.io Portal associated with this request
  "x-chainio-flow-id": "a84cb072-06d1-4ee9-bbb9-84f0285ca54d"
}

content-type: application/json
x-chainio-signature: EUGgz5Vm0hXT9RJg41niEH+TBH2pAGrIIzBGT1zwPfw=
x-chainio-execution-id: db5f657d-f9c9-49cd-92ac-1e321f086500
  • content-type - This will always be application/json
  • x-chainio-signature - This represents an HMAC SHA256 signature Chain.io will generate using the body of the request and theshared_secret associated with the adapter. This signature should be utilized by your adapter to verify that the request originated from Chain.io. See the Create Adapter or Update Adapter Shared Secret Value endpoints for more information.
  • x-chainio-execution-id - This value uniquely identifies each Chain.io Flow execution. It can be used for tracing purposes to tie the HTTP request sent by Chain.io back to an execution in the Chain.io portal. Because it is unique per each request, it can also be used internally by the adapter for any other tracing, debugging, or logging purposes.
  • x-chainio-workspace-id - This value uniquely identifies which Chain.io workspace the request originated from. It can potentially be used to uniquely identify a customer's workspace for caching, rate limiting or other purposes requiring knowledge of which Chain.io Portal Workspace the request belongs to.
  • x-chainio-flow-id - This value uniquely identifies the Chain.io Portal Flow (integration) the request is associated with. Every flow exists inside of a single Workspace. The flow id can be used as an additional dimension for caching, rate limiting or other purposes.

Adapter Webhook Response

When your adapter receives the webhook HTTP request, it must respond with a 200 HTTP status code.

You may either respond synchronously with the POST body defined by the callback API endpoint, otherwise you must respond with a message payload like the example below and interact with the callback API endpoint asynchronously.

If your service responds with a 4xx response code, the Flow Execution will stop with an error status.

If your service responds with a 5xx response code, the Flow Execution will stop with a bug status.

Regardless of status code, you may respond with a JSON body with a message attribute which will be added to the User Log for this execution in the Chain.io Portal. If your service responds with a 200 code, then the message will be added as an info message. For 4xx and 5xx statuses, then the message will be added as an error message.

{
  "message": "Service received request"
}

The maximum payload size for both synchronous and asynchronous responses is 600MB. Any payload received larger than that will stop the Flow Execution with an Error status.

Timeout

Your service must respond within 45 seconds or the Flow Execution will be terminated with a Bug status and a user log message will be added saying that your service was unresponsive. If you need to run long running processes, then respond with the message payload and call the callback API endpoint separately.