Configure webhooks

To configure a destination webhook, you must first create an auth, then one or more destinations for the auth, and then one or more event bindings that trigger each destination.

You may want to configure webhooks to:

• Send processed transaction data to an external system. You can optionally attach a Stedi mapping to transform the payload before sending it to the destination.
  We recommend only using a mapping with a destination when you know your mapping output will be under 1MB in size. Otherwise, you can use the Map Transaction Output endpoint to retrieve mapped data asynchronously.

• Send Stedi events to systems like Slack and PagerDuty or to implement more advanced functionality.

​

Auth

An auth defines how to authenticate with a specific API. You can use a single auth configuration across multiple destinations. Stedi supports the following types of auth configurations.

Type	Description
API Keys	The API keys as headers in the request. The most common version is ‘bearer tokens’.
Basic Auth	HTTP Basic Auth, where you provide a username and password.
OAuth 2.0	OAuth 2.0 Auth, where you can set the Authorization endpoint and parameters, the HTTP method, a client ID, and a client secret.

​

Unauthenticated endpoints

There isn’t a ‘no-auth’ option with Destinations, but you can achieve this by configuring the API Keys auth to use arbitrary values for Header name and Value (e.g. Header name: x-stedi-noauth and Value: dummy). Since the receiving API isn’t authenticating the call, it will ignore these values and accept the request.

​

Create auth

To create a new auth:

1. Go to the Destinations page.
2. Click Add new auth.
3. Enter a name for the auth.
4. Choose the appropriate Authentication type.
5. Enter the details for the auth.
6. Click Done.

​

Destination

The destination defines which URL endpoint should be called when the destination is invoked, and which HTTP method to use (POST, PUT, GET, PATCH, DELETE).

Destinations are scoped to a single auth. However, you might have multiple destinations for a single system integration, each with a different endpoint. For example, one endpoint for creating Sales Orders and another for Item Fulfillments.

​

Create destination

To create a new destination:

1. Go to the Destinations page.
2. Under the desired auth, click Add destination.
3. Enter a name.
4. Choose a Method and enter an Endpoint.
5. (Optional) Enter a Max executions per second. Use this to avoid overloading the target service.

​

Event bindings

Event bindings allow you to specify which events trigger the destination webhook. You can create multiple event bindings for a single destination. For example, you may want to create an event binding for each type of transaction you want to send to your API.

​

Create event binding

To create a new event binding:

1. Go to the Destinations page.
2. Click the desired destination.
3. Click the Edit tab.
4. Click Add event binding.
5. Choose an Event detail-type and complete the remaining fields.
6. (Optional) Select a mapping to transform the payload before sending it to the destination. This is only available for transaction.processed.v2 and fragment.processed.v2 events.
7. Click Create binding.

​

Send transaction data

You can create a transaction.processed.v2 event binding to send processed transaction data to external APIs. If the transaction set uses fragments to split the payload into smaller chunks, you can also configure an event binding for fragment.processed.v2 events.

You can optionally add a Stedi mapping to both types of event bindings to transform the payload shape before sending it to the destination.

​

Event types

Stedi emits a transaction.processed.v2 event each time it processes a transaction. An EDI file can contain multiple transactions, so a single EDI file can produce multiple events that each invoke the configured destination webhook. When you use a transaction.processed.v2 event to trigger a destination, Stedi includes the Guide JSON transaction in the payload along with the event data.

The transaction itself is only included as part of the event if the whole response (payload + event) is < 1MB. Otherwise, the event will contain a section that specifies the transaction was too big to be included and you can retrieve the actual transaction by making a request to the transaction artifact.

When fragments are enabled, the transaction.processed.v2 payload includes an empty array in place of the fragmented segment. Stedi then emits one fragment.processed.v2 event for each fragment within the processed transaction. The event contains a link you can use to retrieve the fragment data as well as information about the original transaction, such as the ISA and GS headers.

Refer to Events for complete details and examples.

​

Configure event bindings

Choose transaction.processed.v2 or fragment.processed.v2 as the Event detail-type and complete the following fields:

1. (Optional) Choose a Transaction set ID. This is useful if you want to send different transaction sets to different endpoints. For example, you could send 850 Purchase Orders to one endpoint and 860 Purchase Order Change Requests to another.
2. (Optional) Choose a Partnership ID. This is useful if you want to send transactions from different partners to different endpoints. For example, you could send transactions from Walmart to one endpoint and transactions from Target to another. This is less common.
3. (Optional) Select a Guide. This is useful if you want to send transactions parsed using different guides to different endpoints. For example, you may receive 005010 850 Purchase Orders from two different retailers, and those retailers have different guides. Since the transaction payloads will differ, you may want to send them to different API endpoints within your system.
4. (Optional) You can configure the following Advanced settings fortransaction.processed.v2 events:
   • Connection ID: This is useful when you are using multiple connections for a single partnership. For example, you may have set up one connection type for test data and a separate connection for production data.
   • Mode: Specify the type of data Stedi is sending to the destination. You can choose from Test or Production.
5. (Optional) Select a Guide + Mapping. This is useful if you want to send transactions parsed using different guides to the same endpoint. For example, you may receive 005010 850 Purchase Orders from two different retailers, and those retailers have different guides. Since the transaction payloads will differ, you can choose a mapping to convert the 850s to your API shape.
   If you plan to add a mapping to this event binding, you must select a guide. When you add a mapping, you are only able to select a mapping that uses the same guide as a source.

​

Transform data with mappings

Stedi integrations use Guide JSON, a JSON format that closely reflects the structure of an EDI transaction. You may need to reshape transaction data from Guide JSON format into the shape required for the target API. For example, you may need to rename fields, add or remove fields, or change the data type of a field.

You can use the Mappings module to transform your payload into the required shape before sending it to a destination.

​

Size limits

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.

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.

​

Add a Stedi mapping

To add a mapping:

1. Use the mappings editor to create a transformation for the event. You must choose the event when creating the source schema. Refer to the mappings documentation for instructions.
2. Select the mapping in the Mapping menu when creating your event binding. You will only be able to select mappings that use the same guide you selected in the event binding.

Stedi will apply the mapping to the event data before sending it to the destination.