Events types and structure

Stedi emits events as it processes and generates EDI files. You can use these events to trigger webhooks, trigger alerts in systems like Slack or PagerDuty, and implement more advanced functionality.

​

Event types

Stedi emits the following types of events.

​

Transaction processed

The transaction.processed.v2 event is the primary integration point for transactions you receive from your trading partner. Stedi emits one transaction.processed.v2 event for every transaction successfully processed.

Since an EDI file can contain multiple transactions, a single EDI file can result in multiple transaction.processed.v2 events.

{
  "event": {
    "version": "0",
    "id": "d709a648-978e-4398-994f-7baa58e4fee5",
    "detail-type": "transaction.processed.v2",
    "source": "stedi.core",
    "account": "012345678910",
    "time": "2023-08-28T20:55:59Z",
    "region": "us-east-1",
    "resources": [
      "https://core.us.stedi.com/2023-08-01/transactions/7821ec6b-cbd4-4534-91f9-8eed36f4230a"
    ],
    "detail": {
      "transactionId": "7821ec6b-cbd4-4534-91f9-8eed36f4230a",
      "direction": "INBOUND",
      "mode": "production",
      "fileExecutionId": "40e33f06-918a-37ad-c66c-4716119aa473",
      "processedAt": "2023-08-28T20:55:59.202Z",
      "artifacts": [
        {
          "artifactType": "application/edi-x12",
          "usage": "input",
          "url": "https://core.us.stedi.com/2023-08-01/transactions/7821ec6b-cbd4-4534-91f9-8eed36f4230a/input",
          "sizeBytes": 61
        },
        {
          "artifactType": "application/json",
          "usage": "output",
          "url": "https://core.us.stedi.com/2023-08-01/transactions/7821ec6b-cbd4-4534-91f9-8eed36f4230a/output",
          "sizeBytes": 393
        }
      ],
      "partnership": {
        "partnershipId": "ACME_BSW",
        "partnershipType": "x12",
        "sender": {
          "profileId": "BSW"
        },
        "receiver": {
          "profileId": "ACME"
        }
      },
      "x12": {
        "transactionSetting": {
          "guideId": "01H0QXXXX",
          "transactionSettingId": "01H8J1YXXX"
        },
        "metadata": {
          "interchange": {
            "acknowledgmentRequestedCode": "1",
            "controlNumber": 19
          },
          "functionalGroup": {
            "controlNumber": 19,
            "release": "004010",
            "date": "2023-08-25",
            "time": "18:23:02",
            "functionalIdentifierCode": "IN"
          },
          "transaction": {
            "controlNumber": "1",
            "transactionSetIdentifier": "810"
          },
          "receiver": {
            "applicationCode": "ACME",
            "isa": {
              "qualifier": "ZZ",
              "id": "ACME"
            }
          },
          "sender": {
            "applicationCode": "BSW",
            "isa": {
              "qualifier": "ZZ",
              "id": "BSW"
            }
          }
        }
      },
      "connectionId": "01H1CH2ZES1Z8AW94A3RQSRWRW" // optional
    }
  }
}

When fragments are enabled on the transaction, Stedi emits one transaction.processed.v2 event and one fragment.processed.v2 event for each fragment.

​

Retrieve transaction data

You can use the documentDownloadUrl URLs in the event.detail.artifacts objects to fetch transaction data from Stedi.

• Use the URL in the artifact with "usage": "input" to fetch the input for the transaction. For inbound transactions, this is the EDI you received from your trading partner.
• Use the URL in the artifact with "usage": "output" to fetch the output for the transaction. For inbound transactions, this is processed transaction data in Guide JSON format.

To retrieve transaction data, make a request with the URL and your Stedi API key for authorization.

If your HTTP library automatically follows redirects, you will receive the transaction data in the response body. If it does not follow redirects, the response includes a documentDownloadUrl that you can use to retrieve the transaction data.

The following example shows a cURL request to retrieve transaction data. This example uses the -L option for following redirects.

curl -L -H "Authorization: ${STEDI_API_KEY}" \
    https://core.us.stedi.com/2023-08-01/transactions/$TRANSACTION_ID/output

​

Fragment processed

You can use fragments to split transaction payloads into smaller chunks for easier downstream processing. By default, a single fragment will include a maximum of 800 repeated segments. You can customize the batch size when creating the transaction setting.

Stedi emits one fragment.processed.v2 event for each fragment within a processed transaction. The payload contains details about the original transaction, including the ISA and GS headers. These details about the original transaction are included in every fragment event.

​

Retrieve transaction data

The following example shows a cURL request to retrieve details about the fragment associated with a transaction. This example uses the -L option for following redirects.

curl -L -H "Authorization: ${STEDI_API_KEY}" \
 'https://core.us.stedi.com/2023-08-01/transactions/$TRANSACTION_ID/edi-platform/fragments/$FRAGMENT_INDEX/output'

​

File processed

You may want to consume file.processed.v2 events when you want to route non-EDI files that arrive on Stedi for additional processing.

Stedi emits a file.processed.v2 event for all successful file executions. You can view details on the Files page.

For files with the following extensions, Stedi emits a file.processed.v2 event but does not attempt to parse them as EDI: .json, .csv, .xml, .xls, .xlsx or .pdf.

{
    "event": {
        "version": "0",
        "id": "d601ab7c-d5d3-4c5f-96f9-6c7479c5594e",
        "detail-type": "file.processed.v2",
        "source": "stedi.core",
        "account": "012345678910",
        "time": "2023-09-06T20:25:03Z",
        "region": "us-east-1",
        "resources": [
          "https://core.us.stedi.com/2023-08-01/executions/xxx-5470-a381-69ca-ee9e4cfa72f7"
        ],
        "detail": {
          "fileExecutionId": "xxx-5470-a381-69ca-ee9e4cfa72f7",
          "processedAt": "2023-09-06T20:25:03.194Z",
          "partnershipId": "ACME_BSW", // optional
          "connectionId": "01H1CH2ZES1Z8AW94A3RQSRWRW", // optional
          "source": {
            "name": "filename.extension"
          },
          "artifacts": [
            {
              "artifactType": "application/edi-x12",
              "usage": "input",
              "sizeBytes": 10036,
              "url": "https://core.us.stedi.com/2023-08-01/executions/xxx-5470-a381-69ca-ee9e4cfa72f7/input",
              "model": "execution"
            },
            {
              "artifactType": "application/json",
              "usage": "metadata",
              "sizeBytes": 2248,
              "url": "https://core.us.stedi.com/2023-08-01/executions/xxx-5470-a381-69ca-ee9e4cfa72f7/metadata",
              "model": "execution"
            }
          ]
        }
      }
}

​

File delivered

Stedi emits the file.delivered.v2 event every time a file is successfully delivered to a connection for an outbound transaction set. This event is only emitted for generated EDI (outbound) files and is not emitted for inbound files.

{
  "version": "0",
  "id": "c4fa0c18-3533-72c6-c447-f56712d0fb75",
  "detail-type": "file.delivered.v2",
  "source": "stedi.core",
  "account": "525407659312",
  "time": "2023-12-18T20:35:28Z",
  "region": "us-east-1",
  "resources": [],
  "detail": {
    "fileExecutionId": "a8858445-a7cb-4f42-adcd-a4603a6f6e91",
    "processedAt": "2023-12-18T20:35:28.265Z",
    "artifacts": [
      {
        "artifactType": "application/json",
        "url": "https://core.us.stedi.com/2023-08-01/executions/a8858445-a7cb-4f42-adcd-a4603a6f6e91/input",
        "usage": "input",
        "sizeBytes": 4604,
        "model": "execution"
      },
      {
        "artifactType": "application/edi-x12",
        "url": "https://core.us.stedi.com/2023-08-01/executions/a8858445-a7cb-4f42-adcd-a4603a6f6e91/output",
        "usage": "output",
        "sizeBytes": 635,
        "model": "execution"
      }
    ],
    "connection": {
      "connectionType": "SFTP",
      "connectionId": "01HHN8QD0S5JSHS964DAW47ZE9"
    },
    "delivery": {
      "status": "DELIVERED",
      "message": "Delivered to 'sftp://transfer.us.stedi.com/outbound/a8858445-a7cb-4f42-adcd-a4603a6f6e91.x12'",
      "artifactId": "a8858445-a7cb-4f42-adcd-a4603a6f6e91.x12"
    }
  }
}

​

Retrieve execution data

Both the file.delivered.v2 and file.processed.v2 events include URLs in the event.detail.artifacts objects you can use to fetch execution data from Stedi.

• The URL for the input artifact allows you to retrieve the input to Stedi. For file.processed.v2 events, this option is helpful when you want to react to and handle non-X12 inbound files flowing through Stedi, such as CSV, TSV, XML, and PDF files.
• The URL for the output artifact allows you to retrieve the output from Stedi. For file.delivered.v2 events, this option retrieves the entire generated EDI file (including the envelope information) that Stedi delivered to your trading partner.
• The URL for the metadata artifact (file.processed.v2 only) allows you to retrieve the execution metadata from Stedi, which includes the processing date and time, the control number, and other information about the file. Metadata is only supported for inbound x12 files.
  Metadata example

  Example X12 metadata response

  {
    "version": "2024-01-01",
    "interchanges": [
      {
        "envelope": {
          "senderQualifier": "ZZ",
          "senderId": "BSW            ",
          "receiverQualifier": "ZZ",
          "receiverId": "ACME           ",
          "date": "2022-05-24",
          "time": "20:01",
          "versionNumberCode": "00401",
          "controlNumber": 93,
          "acknowledgmentRequestedCode": "0",
          "usageIndicatorCode": "P",
          "trailer": {
            "numberOfIncludedFunctionalGroups": 1,
            "controlNumber": 93
          },
          "segments": {
            "isa": "ISA*00*          *00*          *ZZ*BSW            *ZZ*ACME           *220524*2001*U*00401*000000093*0*P*>",
            "iea": "IEA*1*000000093"
          }
        },
        "acknowledgments": [],
        "standard": "x12",
        "span": {
          "start": 0,
          "end": 715
        },
        "delimiters": {
          "segment": "~",
          "element": "*",
          "composite": ">"
        },
        "functionalGroups": [
          {
            "envelope": {
              "functionalIdentifierCode": "SH",
              "applicationSenderCode": "BSW",
              "applicationReceiverCode": "ACME",
              "date": "2022-05-24",
              "time": "20:01",
              "controlNumber": 97,
              "responsibleAgencyCode": "X",
              "release": "004010",
              "trailer": {
                "numberOfIncludedTransactionSets": 1,
                "controlNumber": 97
              },
              "segments": {
                "gs": "GS*SH*BSW*ACME*20220524*2001*97*X*004010",
                "ge": "GE*1*97"
              }
            },
            "span": {
              "start": 104,
              "end": 698
            },
            "transactionSets": [
              {
                "id": "856",
                "controlNumber": "0001",
                "trailer": {
                  "numberOfIncludedSegments": 18,
                  "controlNumber": "0001"
                },
                "span": {
                  "start": 154,
                  "end": 689
                },
                "trackedIdentifiers": {
                  "PRF-01": ["Tx22HNv4d"],
                  "BSN-02": ["VendorShipID"]
                }
              }
            ]
          }
        ]
      }
    ]
  }
  

To retrieve execution data, make a request with the URL and your Stedi API key for authorization.

If your HTTP library automatically follows redirects, you will receive the execution input data in the response body. If it does not follow redirects, the response includes a documentDownloadUrl that you can use to retrieve the transaction data.

The following example shows a cURL request to retrieve execution data. This example uses the -L option for following redirects.

curl -L -H "Authorization: ${STEDI_API_KEY}" \
  https://core.us.stedi.com/2023-08-01/executions/$EXECUTION_ID/input

​

File failed

Stedi emits file.failed.v2 events in two scenarios:

• When a failure occurs while processing an inbound file. Stedi emits the file.failed.v2 event at the file level. If a single transaction set fails, the entire file fails.
• When an outbound file cannot be delivered to a configured connection. Stedi attempts to deliver a file to all configured connections every 6 minutes for up to 3 total attempts. If it cannot deliver the file after the third attempt, it marks the file execution as FAILED and emits the file.failed.v2 event. Stedi displays each delivery attempt and the failure details on the Files page.

{
  "version": "0",
  "id": "0503d39f-fae2-4228-8317-b7f1ef8ffaa5",
  "detail-type": "file.failed.v2",
  "source": "stedi.core",
  "account": "012345678910",
  "time": "2023-11-08T00:30:01Z",
  "region": "us-east-1",
  "resources": [
    "https://core.us.stedi.com/2023-08-01/executions/4664e7de-341b-4ab4-9f4c-bb0f32fea0ba"
  ],
  "detail": {
    "fileExecutionId": "4664e7de-348b-4ab4-9f4c-b40f32fea0ba",
    "direction": "INBOUND",
    "processedAt": "2023-11-08T00:30:01.197Z",
    "source": {
      "name": "filename.edi"
    },
    "artifacts": [
      {
        "artifactType": "application/edi-x12",
        "url": "https://core.us.stedi.com/2023-08-01/executions/4661e7de-348b-4ab4-9f4c-b40f39feb0ba/input",
        "usage": "input",
        "model": "execution"
      }
    ],
    "partnership": {
      "partnershipId": "acme_amazonds",
      "partnershipType": "x12",
      "receiver": {
        "profileId": "acme"
      },
      "sender": {
        "profileId": "amazonds"
      }
    },
    "errors": [
      {
        "message": "Element BEG-02 must equal 'DS' or 'ZZ'; value found was 'SS'",
        "faultCode": "FAILED_TO_TRANSLATE"
      }
    ],
    "x12": {
      "metadata": {
        "interchange": {
          "acknowledgmentRequestedCode": "0",
          "controlNumber": 13
        }
      },
      "receiver": {
        "isa": {
          "qualifier": "ZZ",
          "id": "ACME"
        }
      },
      "sender": {
        "isa": {
          "qualifier": "ZZ",
          "id": "AMAZONDS"
        }
      }
    }
  }
}

​

Retry events

You can retrigger file processing events for successfully processed files. This feature makes it easier to test your end-to-end integration – for example, triggering webhooks – without continually reprocessing the same files.

To retry an event:

1. Go to the Files page.
2. Click the name of the processed file.
3. Go to the Events tab.
4. Click the ellipses (…) next to an event and select Retry.

​

When are events emitted?

Stedi emits events in the following scenarios.

​

An entire file has successfully processed

Consider an EDI file that contains two functional groups, and a total of three transaction sets. When Stedi successfully processes all transaction sets, it generates the following events:

• 1x file.processed.v2 - indicating the entire file was processed successfully.
• 3x transaction.processed.v2 - one event for each transaction set found in both groups.

​

At least one transaction fails to validate

If one or more transaction sets in a file fails validation, Stedi emits a single file.failed.v2 error, indicating that one or more transactions failed to process. Stedi cannot process the entire file until you address those issues.

​

Event structure

All Stedi events follow a standard JSON Schema. The event payload itself does not include the contents of a given file or transaction. Instead, it references an API path to retrieve the entire object.

{
  "version": "0",
  "id": "8a9fc08a-24b2-4eeb-af7c-f96376ea471e",
  "detail-type": "transaction.processed.v2",
  "source": "stedi.core",
  "account": "012345678910",
  "time": "2021-11-12T00:00:00Z",
  "region": "us-east-1",
  "detail": { ... }
}

In addition to their version, id, and time, events have the following fields:

• detail-type - Indicates the type of event, such as transaction.processed.v2 or file.failed.v2
• source - Indicates the component that generated the event. All events use source: “stedi.core”.
• detail - The JSON payload. The schema for each payload is determined by the detail-type.