Events

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

You use the transaction.processed.v2 event slightly differently depending on whether you are using Destination webhooks or Functions.

• 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.
• Functions event bindings receive only the event data, but you can use the URLs provided in the event to retrieve the transaction payloads from inside the function.

{
  "event": {
    "id": "e3c64c7e-1534-cc4f-2bd1-dd2036f5a225",
    "detail-type": "transaction.processed.v2",
    "source": "stedi.core",
    "time": "2023-08-28T20:55:59Z",
    "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": "BSW",
            "isa": {
              "qualifier": "ZZ",
              "id": "ACME"
            }
          },
          "sender": {
            "applicationCode": "ACME",
            "isa": {
              "qualifier": "ZZ",
              "id": "BSW"
            }
          }
        }
      }
    }
  },
  "artifact": {
    "artifactType": "application/json",
    "usage": "output",
    "attachedReason": "WITHIN_SIZE_LIMIT",
    "detail": {
      "heading": {
        "transaction_set_header_ST": {
          "transaction_set_identifier_code_01": "810",
          "transaction_set_control_number_02": 1
        },
        "beginning_segment_for_invoice_BIG": {
          "date_01": "2022-08-22",
          "invoice_number_02": "SINV00070492"
        }
      },
      "summary": {
        "total_monetary_value_summary_TDS": {
          "amount_01": 199.34
        },
        "transaction_set_trailer_SE": {
          "number_of_included_segments_01": 12,
          "transaction_set_control_number_02": 1
        }
      }
    }
  }
}

​

Retrieve transaction data

You can use the URLs in the event.detail.artifacts objects to fetch transaction data from Stedi. You may need to do this if the output is larger than 1MB or if you are using Stedi function event bindings.

• 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 artfiact 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: Key $STEDI_API_KEY" \
    https://core.us.stedi.com/2023-08-01/transactions/$TRANSACTION_ID/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 File Executions 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 extensions.

{
  "id": "xxx-16fa-ac29-7f9f-c008cd443a21",
  "detail-type": "file.processed.v2",
  "source": "stedi.core",
  "time": "2023-09-06T20:25:03Z",
  "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",
    "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"
      }
    ]
  }
}

​

File delivered

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

{
  "id": "xxx-4843-e9bc-350a-b27693e362b8",
  "detail-type": "file.delivered.v2",
  "source": "stedi.core",
  "time": "2023-09-01T15:02:02Z",
  "detail": {
    "fileExecutionId": "xxx-c425-4bd4-94b5-6b35bf174bad",
    "processedAt": "2023-09-01T15:02:02.328Z",
    "artifacts": [
      {
        "artifactType": "application/json",
        "url": "https://core.us.stedi.com/2023-08-01/executions/xxx-c425-4bd4-94b5-6b35bf174bad/input",
        "usage": "input",
        "sizeBytes": 250
      }
    ],
    "connection": {
      "connectionType": "BUCKET",
      "connectionId": "ff42c152-87c5-4916-848d-e60d47fe0e21"
    },
    "delivery": {
      "status": "DELIVERED",
      "message": "File was delivered to 'some-bucket/path/a-file.edi'",
      "artifactId": "66a9f128-c425-4bd4-94b5-6b35bf174bad.x12"
    }
  }
}

​

File failed

Core 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 am outbound file cannot be delivered to a configured connection.

{
  "id": "xxx-f6cf-f35e-3099-d748604813c1",
  "detail-type": "file.failed.v2",
  "source": "stedi.core",
  "time": "2023-09-06T18:05:43Z",
  "resources": [
    "https://core.us.stedi.com/2023-08-01/executions/xxx-cc71-7d97-3511-d9bae060a406"
  ],
  "detail": {
    "fileExecutionId": "xxx-cc71-7d97-3511-d9bae060a406",
    "direction": "OUTBOUND",
    "processedAt": "2023-09-06T18:05:43.861Z",
    "artifacts": [
      {
        "artifactType": "application/edi-x12",
        "url": "https://core.us.stedi.com/2023-08-01/executions/xxx-cc71-7d97-3511-d9bae060a406/input",
        "usage": "input"
      }
    ],
    "errors": [
      {
        "message": "some message here",
        "faultCode": "UNKNOWN_ERROR"
      }
    ]
  }
}

​

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 a total of six 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.

{
  "id": "xxx-05d4-b198-2fde-7ededc63b103",
  "detail-type": "transaction.processed.v2",
  "source": "stedi.core",
  "time": "2021-11-12T00:00:00Z",
  "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 Core events use source: “stedi.core”.
• detail - The JSON payload. The schema for each payload is determined by the detail-type.

​

Event levels

Stedi events are split into two different levels, each representing a different level of granularity. Events are also categorized by their result states, representing success or failure during processing.

1. file: Events with information about a file that has been detected. File events contain summary information about the data type in the file, like X12 EDI, JSON, CSV, XML, etc.
2. transaction: Events with information about a single transaction within an X12 EDI file.

​

Event categories

1. processed: Events are emitted for each event level, but only when Stedi has processed the entire file successfully.
2. failed: Events are only emitted at the file level because Stedi stops processing a file immediately when it finds an invalid transaction set.