Stedi emits events as it processes and generates EDI files. You can use these events to trigger Destination webhooks that forward processed transaction data, 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.

When you receive a transaction.processed.v2 event through a Destination webhook, the payload includes an event object that contains the event data, as well as an artifact object that contains the actual transaction payload.

When fragments are enabled on the transaction, the transaction payload shows an empty array in place of the fragmented segment. Stedi then emits one or more fragment.processed.v2 events containing chunks of the remaining transaction data from the fragmented segment.

​
Retrieve transaction data

You can use the 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

This functionality is available in a Stedi module. Contact us for details.

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 the processed fragment as well as details about the original transaction, including the ISA and GS headers. These details about the original transaction are included in every fragment event.

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.

​
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.

​
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.

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.

​
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.

X12 File where all Transaction Sets are processed successfully

​
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.

X12 File where one Transaction Set fails validation, blocking the entire file

​
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.

JSON event structure example
{
  "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.

​
Event data enrichment

When you consume a transaction.processed.v2, fragment.processed.v2 or file.processed.v2 event, you typically need to fetch the transaction data from the included URL.

However, Stedi may pre-fetch the transaction data when you use destination webhooks. Enriched event payloads include:

  • event - Details about the event. This information is always included in the event payload. Refer to each event type for complete examples.
  • artifact - An artifact object containing some metadata and the full transaction or fragment data in the detail property. When the transaction or fragment data is included, the attachedReason property is set to WITHIN_SIZE_LIMIT.

Note: The file.processed.v2 events are enriched when the file-type is application/edi-x12 or application/json.

​
When does enrichment occur

It depends on the size of the payload, and whether or not mappings are used.

Under 1MBOver 1MB
Destination✅🚫 (Not enriched, but delivered)
Destination with mapping✅🚫 (Fails to deliver, event is put in error queue)

​
Destination

Stedi includes transaction data in the event payload when the payload is under 1MB. If the event payload is over 1MB, Stedi does not include the enriched contents in the payload. Instead, the event sent to the destination contains an artifact with the attachedReason set to SIZE_LIMIT_EXCEEDED, and you can manually fetch the transaction data from the included URL.

​
Destination with mapping

When you configure a Destination webhook, you can attach a Stedi mapping that Stedi will use to transform the payload before sending it to the destination.

Two size limits must be met for Stedi to both deliver the event and include the transaction data in the event payload.

  1. The enriched event must be less than 4 MB when Stedi passes it to the mapping.
  2. The mapping output must be under 1MB.

Destination and mappings size limits

If either of these size limits fails, Stedi considers the event delivery a failure and adds the event to the destination’s error queue. Instead, you can:

  • Use fragments to split the transaction payload into smaller chunks before sending it to a destination.
  • Use the Map Transaction Output endpoint to retrieve processed, mapped transaction data from Stedi.

Was this page helpful?

Monitor transactionsDestinations overview