Configure webhooks

You can set up webhooks that automatically send claim processing events to your endpoint.

These events contain the information you need to retrieve 277CA claim acknowledgment and 835 Electronic Remittance Advice (ERA) responses through Stedi APIs. They can also help you monitor your claims pipeline when you’re submitting claims through Stedi SFTP.

You can either create a single webhook that forwards events from all transactions, or create a separate webhook for each transaction type.

Configuring a webhook involves:

• Creating a credential set for authentication to the endpoint.
• Creating a webhook that specifies the URL where Stedi should deliver events.
• Adding one or more event bindings that trigger the webhook.

​

Credential set

A credential set defines how to authenticate with a specific API. You can use a single credential set across multiple webhooks. Stedi supports the following types of configurations.

​

Unauthenticated endpoints

When using the ‘None’ credential set type in webhooks, it’s functionally the same as using ‘API Keys’. However, we set a dummy value for Header name and Value (x-stedi-noauth and dummy). Since the receiving API isn’t authenticating the call, it will ignore these values and accept the request.

​

Create credential set

You can define a credential set as part of configuring a new webhook. You can also create a new credential set independently and then attach it to one or more webhooks.

To create a credential set:

1. Go to the Webhooks page.
2. Click Manage credentials, and then click Create credential set.
3. Enter a name.
4. Choose the appropriate Authentication type.
5. Enter the details.
6. Click Create credential set.

​

Webhook

A webhook defines which URL endpoint Stedi should call when the webhook is invoked, and which HTTP method to use (POST, PUT, GET, PATCH, DELETE).

You can only attach one credential set to each webhook. However, you might have multiple webhooks for a single system integration, each with a different endpoint.

​

Create webhook

To create a new webhook:

1. Go to the Webhooks page.
2. Click Create webhook.
3. Enter a name.
4. Choose a Method and enter an Endpoint URL. This is where Stedi delivers the events when the webhook is invoked.
5. Select a Credential set to use for authentication or create a new one for this endpoint.
6. (Optional) Set the Concurrency. You can set the maximum number of deliveries that Stedi will attempt to deliver to the endpoint at one time. This can help you avoid overloading the target service.

​

Event bindings

Event bindings allow you to specify which events trigger the webhook. You can create multiple event bindings for a single webhook. 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 Webhooks page.
2. Click the webhook.
3. Click the Event bindings tab.
4. Click New event binding.
5. Choose Transaction processed as the Event type.
6. (Optional) Set one or more filters.
7. Click Create binding.

​

Choosing event types

The recommended event bindings depend on your use case:

• API claim submission: At a minimum, you should create an event binding for transaction processed events because they contain the information you need to retrieve claim responses from Stedi. You may also want to set up event bindings for file delivered and file failed events.
• SFTP claim submission: At a minimum, you should create an event binding for file failed events because they’re emitted when Stedi is unable to deliver your claim to the payer. You may also want to set up event bindings for file delivered events and transaction processed events.

Transaction processed events

Stedi emits a transaction processed event after it successfully receives and translates a payer or intermediary clearinghouse response into JSON. It also emits this event once it successfully translates a JSON claim submission into X12 EDI format for the payer. The event payload contains the information you need to retrieve processed responses through Stedi APIs:

• x12.transactionSetIdentifier specifies the transaction type (277 or 835).
• transactionId allows you to retrieve the transaction in JSON format using either the 277CA Report or 835 ERA Report endpoint.
• fileExecutionId allows you to retrieve the transaction in X12 EDI format through the Get Execution Input endpoint.

Even if you plan to retrieve claim responses through Stedi SFTP, you may want to monitor these events so you can receive alerts when new claim responses are available.

File delivered events

Stedi emits a file delivered event when it successfully generates and delivers a claim. You may want to send these events to your system for monitoring and alerting.

Note that this event is emitted when Stedi delivers your claim to our connection with the payer. It doesn’t indicate whether the payer received the claim or whether they have accepted or rejected it.

File failed events

Stedi emits a file failed event when it either fails to process a response from a payer or cannot deliver a submitted claim.

If you’re submitting claims through Stedi’s SFTP connection, we strongly recommend monitoring these events so that you can receive instant notifications when a submitted claim fails due to validation errors in the EDI file.

File failed events can indicate connection problems or other issues that our engineering team must resolve with the payer. If you’re submitting claims through Stedi APIs, you may want to also monitor these events so you can alert our customer support team if needed.

​

Event filters

You may want to further filter the events Stedi sends to your endpoint:

• Transaction: This is useful if you want to send events for 277CA claim acknowledgments to one endpoint and events for 835 ERAs to another. For example, if you set this to 835: Health Care Claim Payment/Advice, Stedi only sends events for processed 835 ERAs to your endpoint.
• Partnership: This is useful if you want to send test claims to one endpoint and production claims to another. For example, if you set this to local-clearinghouse-test, Stedi only sends events for test claims to your endpoint.

​

Event schema

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": "<ACCOUNT_ID>",
  "time": "2021-11-12T00:00:00Z",
  "region": "us-east-1",
  "resources": [
    "https://core.us.stedi.com/2023-08-01/transactions/3543b3f7-0d78-48cc-97c3-ac145e250a1d" 
  ],
  "detail": { ... }
}

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

• 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”.
• account - The account ID that generated the event.
• region - The AWS region where the event was generated.
• resources - The URL to the resource that Stedi created. This could be a transaction or a file execution, depending on the event type. Hitting the URL with your API key is equivalent to calling the Get Execution and Get Transaction endpoints.
• detail - The JSON payload. The schema for each payload is determined by the detail-type.

​

HTTP response codes

Stedi considers a 2xx response a success, and marks any other response as a failure.

Stedi retries events associated with status codes other than 2xx for up to 4 times with a 90 second wait period inbetween retries.

If the maximum number of retries has been exhausted, Stedi adds the event to the error queue for the webhook.

You can set the Concurrency when configuring the webhook to prevent throttling. This setting determines the maximum number of deliveries that Stedi will attempt to deliver to the endpoint at one time.

​

Timeouts

The target endpoint must respond with a 2xx status code within 5 seconds, or the event will be counted as a failed delivery.

Because of this timeout limitation, we recommend designing your webhook endpoints to immediately acknowledge receipt with a 2xx response, then process the data asynchronously. See Best practices for webhook endpoints.

​

Retries and duplicate deliveries

When a delivery fails, Stedi will retry up to 4 times every 90 seconds. After the fifth retry, Stedi moves the event to the error queue.

If your webhook doesn’t respond within 5 seconds, Stedi marks that as a failure and then automatically retries. This can result in duplicate deliveries.

​

Error queue

Each webhook includes an error queue. Each item in the queue consists of the original event that was attempted to be delivered. This ensures if the target service has some downtime, or anything else goes wrong, the missed events can be retried later. The error queue retains items for 14 days.

The order of the error queue is not guaranteed. The downstream service must be designed to be idempotent to handle at-least-once delivery of events, and must accept events out of order.

​

Logs

To view logs, click the webhook to go to its detail page, and then navigate to the Logs tab.

​

Deauthorized connections

If a webhook sends a message to an endpoint that returns a 401 (Unauthorized) response, the destination will be ‘deauthorized’. In this state, the webhook won’t be able to deliver messages.

If there is an issue with your authentication information (such as the password, API key, or OAuth settings), edit the webhook to fix it.

If the authentication information is correct, and there was a different reason for the endpoint returning a 401, you can try again by adding a temporary header. For example, x-stedi-reauthorize with today’s date as a value. When you save, the webhook will attempt to deliver again. This header can be removed later. Editing the value of a header will also restart deliveries.

You will likely have a queue of messages to deliver, so Stedi will automatically start retrying them after you make this change. If the endpoint is still returning an invalid response, the webhook will return to Deauthorized.

​

Best practices for webhook endpoints

When creating endpoints to receive webhooks from Stedi, we recommend the following architecture:

1. Acknowledge first, process later: Design your endpoint to immediately return a 2xx status code to acknowledge receipt, then process the payload asynchronously.
2. Store payloads for processing: Capture the webhook data in a queue, database, or other storage mechanism before processing.
3. Process asynchronously: Handle the actual business logic in a separate process or worker after acknowledging receipt.
4. Implement idempotency: Use idempotency keys from the event payload to prevent duplicate processing.
   • Store the eventId from each webhook payload in your database
   • Before processing an incoming webhook, check if its eventId has already been processed
   • Design operations to be idempotent, ensuring that processing the same event multiple times doesn’t cause issues (e.g., avoid incrementing counters on each processing attempt)

This architecture prevents timeouts, handles potential duplicate deliveries, and allows you to process high volumes of events.