Configure webhooks for claim responses

You can set up webhooks that automatically send events for processed 277s and 835s to your endpoint. The event payload contains the information you need to retrieve these responses from Stedi. 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

At a minimum, you should create an event binding for transaction processed events. You may also want to set up event bindings for file delivered and file failed events, depending on your use case.

(Recommended) Transaction processed events

Stedi emits a transaction processed event after it successfully receives and translates a payer or peer clearinghouse response into JSON. The event payload contains the information you need to retrieve processed responses from Stedi:

• x12.transactionSetIdentifier specifies the transaction type (277 or 835).
• transactionId allows you to retrieve the transaction from Stedi using either the 277CA Report or 835 ERA Report endpoint.

{
  "version": "0",
  "id": "f972fb53-653a-1747-ce30-bed15fc04f5c",
  "detail-type": "transaction.processed.v2",
  "source": "stedi.core",
  "account": "000000112345",
  "time": "2024-07-18T16:21:24Z",
  "region": "us-east-1",
  "resources": [
    "https://core.us.stedi.com/2023-08-01/transactions/f0d3f790-0bc9-432b-93kd-e4b7ece67946"
  ],
  "detail": {
    "transactionId": "f0d4f780-0ec9-432b-93gd-e4b7ece93946",
    "direction": "INBOUND",
    "mode": "test",
    "fileExecutionId": "9f76b485-6hca-43bf-917e-d5b54bec6234",
    "processedAt": "2024-07-18T16:21:24.658Z",
    "fragments": null,
    "artifacts": [
      {
        "artifactType": "application/edi-x12",
        "usage": "input",
        "url": "https://core.us.stedi.com/2023-08-01/transactions/f0d9f790-0ec9-431b-93fd-e4h7ece63946/input",
        "sizeBytes": 1313,
        "model": "transaction"
      },
      {
        "artifactType": "application/json",
        "usage": "output",
        "url": "https://core.us.stedi.com/2023-08-01/transactions/f0d3f740-0ec9-432b-98fd-e4b7ece63946/output",
        "sizeBytes": 5602,
        "model": "transaction"
      }
    ],
    "partnership": {
      "partnershipId": "local-clearinghouse-test",
      "partnershipType": "x12",
      "sender": {
        "profileId": "clearinghouse-test"
      },
      "receiver": {
        "profileId": "local"
      }
    },
    "x12": {
      "transactionSetting": {
        "guideId": "01J1M50C1Q44KYDZY8V7R1TPBW",
        "transactionSettingId": "01J1M50P9623BFE0FFT5Q2BR49"
      },
      "metadata": {
        "interchange": {
          "acknowledgmentRequestedCode": "0",
          "controlNumber": 11
        },
        "functionalGroup": {
          "controlNumber": 11,
          "release": "005010X214",
          "date": "2024-07-18",
          "time": "16:20:47",
          "functionalIdentifierCode": "HN"
        },
        "transaction": {
          "controlNumber": "1001",
          "transactionSetIdentifier": "277"
        },
        "receiver": {
          "applicationCode": "001690149382",
          "isa": {
            "qualifier": "ZZ",
            "id": "001690149382"
          }
        },
        "sender": {
          "applicationCode": "STEDITEST",
          "isa": {
            "qualifier": "ZZ",
            "id": "STEDITEST"
          }
        }
      }
    },
    "connectionId": "01J1M5124B2HWMNN91Q3Z6AM61"
  }
}

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.

{
  "version": "0",
  "id": "4f50b580-7951-7170-2294-f201cba2a587",
  "detail-type": "file.delivered.v2",
  "source": "stedi.core",
  "account": "000011123456",
  "time": "2024-07-10T22:05:37Z",
  "region": "us-east-1",
  "resources": [],
  "detail": {
    "fileExecutionId": "b727b8b7-1f00-4021-bc6e-e41944d206d8",
    "processedAt": "2024-07-10T22:05:37.541Z",
    "artifacts": [
      {
        "artifactType": "application/json",
        "url": "https://core.us.stedi.com/2023-08-01/executions/b727b8e7-1g00-4011-be6c-e41444d409d8/input",
        "usage": "input",
        "sizeBytes": 7095,
        "model": "execution"
      },
      {
        "artifactType": "application/edi-x12",
        "url": "https://core.us.stedi.com/2023-08-01/executions/b727b8e7-1g00-4011-be6c-e41444d409d8/output",
        "usage": "output",
        "sizeBytes": 1047,
        "model": "execution"
      }
    ],
    "connection": {
      "connectionType": "BUCKET",
      "connectionId": "01J2A10FGXPS2D896HHY9SS9V6"
    },
    "delivery": {
      "status": "DELIVERED",
      "message": "Delivered to 'healthcare-583246444612-455190814958/clearinghouse/incoming/b727b8e7-1f00-4011-bc6e-e41444d406d8.x12'",
      "artifactId": "b727b8e7-1f00-4011-bc6e-e41444d406d8.x12"
    }
  }
}

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.

We monitor for file failed events internally because they are usually the result of connection problems or other issues that our engineering team must resolve with the payer. However, you may want to also monitor these events so you can alert our customer support team if needed.

{
  "version": "0",
  "id": "94408f31-f6hd-f8e3-e3bb-79544545cch0",
  "detail-type": "file.failed.v2",
  "source": "stedi.core",
  "account": "00000111234",
  "time": "2024-07-10T22:06:28Z",
  "region": "us-east-1",
  "resources": [
    "https://core.us.stedi.com/2023-08-01/executions/fgcb0ae8-ae51-444f-bb3e-2e2897ac4efb"
  ],
  "detail": {
    "fileExecutionId": "ffcb0ae8-ae52-444f-bb3e-2e2595ac4ffb",
    "direction": "INBOUND",
    "processedAt": "2024-07-10T22:06:28.442Z",
    "source": {
      "name": "2029eb3d-03f3-43e0-b8fc-d441c3485016.x12"
    },
    "artifacts": [
      {
        "artifactType": "application/edi-x12",
        "url": "https://core.us.stedi.com/2023-08-01/executions/ffcg0ae8-ae51-474f-bb3e-2e2895ah4cfa/input",
        "usage": "input",
        "model": "execution"
      }
    ],
    "connectionId": "01J2A10K440H82KXBA2D9W0910",
    "partnership": {
      "partnershipId": "local-clearinghouse-test",
      "partnershipType": "x12",
      "receiver": {
        "profileId": "local"
      },
      "sender": {
        "profileId": "clearinghouse-test"
      }
    },
    "errors": [
      {
        "message": "Element ST-03 must equal '005010X231'; value found was '005010X231A1'",
        "faultCode": "FAILED_TO_TRANSLATE"
      }
    ],
    "x12": {
      "metadata": {
        "interchange": {
          "acknowledgmentRequestedCode": "0",
          "controlNumber": 1
        }
      },
      "receiver": {
        "isa": {
          "qualifier": "ZZ",
          "id": "455190814958"
        }
      },
      "sender": {
        "isa": {
          "qualifier": "ZZ",
          "id": "STEDITEST"
        }
      }
    }
  }
}

​

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 277 Claim Acknowledgments to one endpoint and events for 835 ERAs (claim payments) to another. For example, if you set this to 277: Health Care Information Status Notification, Stedi only sends events for processed 277s 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.

​

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.

​

Response time

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

​

Retries

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.

​

Duplicate deliveries

If your webook doesn’t respond within 5 seconds, Stedi marks that as a failure and then automatically retries. This can result in duplicate deliveries, so we strongly recommend implementing ways to manage duplicates delivered through webhooks.

​

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.