Stedi home page
Docs

Events and message schema

You can configure event destinations for Stedi transaction enrollment events, Core file processing events, and OAuth app events.

Message schema

Stedi sends relevant events as a POST HTTP request to the specified destination URL. Stedi uses the following schema for event destination deliveries.

Headers

Each event delivery includes the following required headers:

HeaderTypeDescription
attempt-numberintegerThe delivery attempt number. The initial delivery is 1.
attempt-typeenumWhether the attempt originated from Stedi (AUTOMATIC) or was a manual retry (MANUAL).
destination-idstringThe identifier for the event destination,formatted as dst_{UUID}.
event-idstringThe event identifier, formatted as evt_{UUID}.
user-agentstringStedi-Events/1.0 (+https://www.stedi.com/docs/healthcare/event-destinations-message-handling). The product token Stedi-Events/1.0 is stable. Match on the Stedi-Events/ prefix in firewall or CDN rules that require a User-Agent. The comment in parentheses is informational and can change without notice.
webhook-idstringA unique message identifier per the Standard Webhooks specification, formatted as msg_{UUID}. You can use this to check for duplicate event deliveries.
webhook-signaturestringA Stedi-generated signature, formatted as v1,{signature}. Use this to verify message authenticity.
webhook-timestampintegerA Unix timestamp indicating when Stedi created the event. This is different from when Stedi delivered the event. You can use this to verify the time of receipt.

The following example headers show that this is the original delivery (attempt-number: 1) from Stedi.

attempt-number: 1
attempt-type: AUTOMATIC
destination-id: dst_019d30e3-5e39-7ab3-9a2e-fcf8218a313d
event-id: evt_b73ae1d2-9128-90b5-60ff-7479ab8b30ac
user-agent: Stedi-Events/1.0 (+https://www.stedi.com/docs/healthcare/event-destinations-message-handling)
webhook-id: msg_b73ae1d2-9128-90b5-60ff-7479ab8b30ac
webhook-signature: v1,Z5wMZ2rqRMsnGdfKzOLnRv1SIwivsLFCGQzJH7eCmlU=
webhook-timestamp: 1774641758

Event payload

Stedi events use a thin event schema. Thin events notify you that a resource has changed but don't include the resource's data. Once you receive an event, verify the resource's state and retrieve details using Stedi's APIs or the Stedi portal.

The event payload schema is available in the Get Event Destination Event endpoint's eventPayload.v1Event object.

Data retention

By default, Stedi returns event data and displays delivery attempts from the past 30 days. Contact us if you need access to older event data.

Events

You can subscribe to transaction enrollment events, file processing events, and OAuth app events. You can also trigger a generic test event from within the Stedi portal to test your event destinations.

Test event

You can trigger this event to validate that you configured your event destination correctly and it receives events.

event.ping

{
  "id": "evt_019d51b6-8d19-71c3-8f5f-cfb55830b618",
  "object": "v1.event",
  "created": "2026-04-03T05:00:11.417Z",
  "environment": "PRODUCTION",
  "resource": {
    "type": "destination",
    "id": "dst_019d51b6-707c-7920-8569-de40061cbe5c"
  },
  "account": "cd26e999-2cb9-4c64-be13-f7375e640b83",
  "type": "event.ping"
}

Transaction enrollment events

Subscribe to these events to track changes in your transaction enrollment requests.

enrollment.activated

Stedi generates this event when a transaction enrollment request is set to LIVE status. This indicates that the enrollment process is complete, and the specified provider can begin exchanging the listed transaction types with the payer.

You can use the enrollment ID in resource.id to retrieve details through the Retrieve Enrollment endpoint or the Enrollments page in the Stedi portal.

{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-03-30T23:19:00.501Z",
  "environment": "PRODUCTION",
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "resource": {
    "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
    "type": "enrollment"
  },
  "type": "enrollment.activated"
}

enrollment.rejected

Stedi generates this event when a transaction enrollment request is set to REJECTED status. This indicates that the payer rejected the enrollment. Common reasons for rejection include incorrect details in the request and the provider not completing the credentialing process with the payer. Customer support contacts you with reasons for rejection and next steps.

You can use the enrollment ID in resource.id to retrieve details through the Retrieve Enrollment endpoint or the Enrollments page in the Stedi portal.

{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-03-30T23:18:52.772Z",
  "environment": "PRODUCTION",
  "id": "evt_8c28ce2e-5d4f-ae1c-fddb-e2421245a873",
  "object": "v1.event",
  "resource": {
    "id": "019bb4e9-5209-7e83-bc84-0db436be7e00",
    "type": "enrollment"
  },
  "type": "enrollment.rejected"
}

enrollment.updated

Stedi generates this event when a transaction enrollment request changes, such as an update to its status, payer, contacts, provider details, tasks, or documents. Use it to keep your records in sync with the latest state of the enrollment.

You can use the enrollment ID in resource.id to retrieve details through the Retrieve Enrollment endpoint or the Enrollments page in the Stedi portal.

{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-03-30T23:19:00.501Z",
  "environment": "PRODUCTION",
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "resource": {
    "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
    "type": "enrollment"
  },
  "type": "enrollment.updated"
}

enrollment.task.assigned

Stedi generates this event when it assigns a new enrollment task to the provider. Tasks describe actions the provider must take to move the enrollment forward. When Stedi assigns a new task, the enrollment status changes to PROVIDER_ACTION_REQUIRED.

You can use the task ID in resource.id and the enrollment ID in relatedResources[].id to retrieve details through the Retrieve Enrollment endpoint or the Enrollments page in the Stedi portal.

{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-04-24T10:00:00.000Z",
  "environment": "PRODUCTION",
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "resource": {
    "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
    "type": "enrollment.task"
  },
  "relatedResources": [
    {
      "id": "019bb4e9-5209-7e83-bc84-0db436be7e00",
      "type": "enrollment"
    }
  ],
  "type": "enrollment.task.assigned"
}

enrollment.task.completed

Stedi generates this event when the provider completes an enrollment task. This indicates that the provider finished the requested action, such as uploading a document or providing an identifier.

You can use the task ID in resource.id and the enrollment ID in relatedResources[].id to retrieve details through the Retrieve Enrollment endpoint or the Enrollments page in the Stedi portal.

{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-04-24T10:00:00.000Z",
  "environment": "PRODUCTION",
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "resource": {
    "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
    "type": "enrollment.task"
  },
  "relatedResources": [
    {
      "id": "019bb4e9-5209-7e83-bc84-0db436be7e00",
      "type": "enrollment"
    }
  ],
  "type": "enrollment.task.completed"
}

enrollment.task.deleted

Stedi generates this event when Stedi deletes an enrollment task assigned to the provider. This typically occurs when a new task supersedes an existing one for a payer. For example, if the requirements for the enrollment process change, we delete the old task and create a new one that reflects the updated requirements. When you receive this event, the deleted task is no longer needed to move the enrollment forward.

You can use the task ID in resource.id and the enrollment ID in relatedResources[].id to retrieve details through the Retrieve Enrollment endpoint or the Enrollments page in the Stedi portal.

{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-04-24T10:00:00.000Z",
  "environment": "PRODUCTION",
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "resource": {
    "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
    "type": "enrollment.task"
  },
  "relatedResources": [
    {
      "id": "019bb4e9-5209-7e83-bc84-0db436be7e00",
      "type": "enrollment"
    }
  ],
  "type": "enrollment.task.deleted"
}

File processing events

Subscribe to these events to track file and transaction processing.

file.processed

Stedi generates this event when it successfully processes a file. For example, Stedi emits a file.processed event when the payer sends a 277CA claim acknowledgment. Use the execution ID in resource.id to retrieve the file data through the Retrieve File Execution Input endpoint.

{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-03-30T23:19:00.501Z",
  "environment": "PRODUCTION",
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "resource": {
    "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
    "type": "execution"
  },
  "type": "file.processed"
}

file.failed

Stedi generates this event when it fails to process a file. For example, Stedi generates a file.failed event when it can't parse an SFTP claim submission. Monitor these events to identify processing errors, including parsing issues or connection problems. Use the execution ID in resource.id to retrieve the file data through the Retrieve File Execution Input endpoint.

{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-03-30T23:19:00.501Z",
  "environment": "PRODUCTION",
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "resource": {
    "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
    "type": "execution"
  },
  "type": "file.failed"
}

transaction.processed

Stedi generates this event after it successfully receives and translates a transaction. For example, Stedi emits this event when it translates a payer's 277CA claim acknowledgment or 835 Electronic Remittance Advice (ERA) into JSON, or when it translates your JSON claim submission into X12 EDI format for the payer.

A single file with multiple transactions produces one file.processed event and multiple transaction.processed events - one for each transaction in the file. The relatedResources array identifies the transaction type in the format transaction.x12.<transactionSetIdentifier>. For example, transaction.x12.837 represents claim submissions, transaction.x12.835 represents 835 Electronic Remittance Advice (ERAs), and transaction.x12.277 represents 277CA claim acknowledgments.

The relatedResources array contains two entries you can use to retrieve the transaction data: the transaction itself and the file execution it came from.

  • JSON format (277CA and 835 only): Call the Get 835 ERA Report or Get 277CA Report endpoint with the transaction ID, which is relatedResources[].id for the transaction.x12.<transactionSetIdentifier> entry.
  • X12 EDI format: Call the Retrieve File Execution Input endpoint with the execution ID, which is relatedResources[].id for the entry with type set to execution. The endpoint returns the entire file. A file usually contains one transaction, but it can contain more.
{
  "account": "11111111-2222-3333-4444-555555555555",
  "created": "2026-03-30T23:19:00.501Z",
  "environment": "PRODUCTION",
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "resource": {
    "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
    "type": "transaction"
  },
  "relatedResources": [
    {
      "id": "019bb508-dc63-73a1-8ddc-9d4720299072",
      "type": "transaction.x12.835"
    },
    {
      "id": "01997873-bebb-7b33-81ef-f408866dfb2c",
      "type": "execution"
    }
  ],
  "type": "transaction.processed"
}

App events

Subscribe to these events to track OAuth app installs and uninstalls in customer accounts.

app.installed

Stedi generates this event when a customer installs your OAuth app in their Stedi account. Stedi delivers the event to your app developer account. Use the app client ID in relatedResources to identify which customer account installed your app.

{
  "id": "evt_a81659f1-16a5-9bec-03e1-0ba8ab5e9652",
  "object": "v1.event",
  "account": "7f3c1b2a-9d40-4e6f-8a11-5c2d9e7b4a03",
  "environment": "PRODUCTION",
  "created": "2026-08-17T14:22:08.000Z",
  "resource": {
    "id": "app_550e8400-e29b-41d4-a716-446655440000",
    "type": "app"
  },
  "relatedResources": [
    {
      "id": "c1e2f3a4-b5c6-4d7e-8f90-1a2b3c4d5e6f",
      "type": "account"
    },
    {
      "id": "stedi_cid_b7e2c1d0-9f8a-4e3b-a6c5-1d2e3f4a5b6c",
      "type": "app.client"
    }
  ],
  "type": "app.installed"
}

app.uninstalled

Stedi generates this event when a customer uninstalls your OAuth app from their Stedi account. Stedi delivers the event to your app developer account. Use the app client ID in relatedResources to identify which customer account uninstalled your app.

{
  "id": "evt_b91760g2-27b6-acbd-14f2-1cb9bc6f9763",
  "object": "v1.event",
  "account": "7f3c1b2a-9d40-4e6f-8a11-5c2d9e7b4a03",
  "environment": "PRODUCTION",
  "created": "2026-08-20T09:05:41.000Z",
  "resource": {
    "id": "app_550e8400-e29b-41d4-a716-446655440000",
    "type": "app"
  },
  "relatedResources": [
    {
      "id": "c1e2f3a4-b5c6-4d7e-8f90-1a2b3c4d5e6f",
      "type": "account"
    },
    {
      "id": "stedi_cid_b7e2c1d0-9f8a-4e3b-a6c5-1d2e3f4a5b6c",
      "type": "app.client"
    }
  ],
  "type": "app.uninstalled"
}
Deliveries and retries
Webhooks (Legacy)

On this page

Message schemaHeadersEvent payloadData retentionEventsTest eventevent.pingTransaction enrollment eventsenrollment.activatedenrollment.rejectedenrollment.updatedenrollment.task.assignedenrollment.task.completedenrollment.task.deletedFile processing eventsfile.processedfile.failedtransaction.processedApp eventsapp.installedapp.uninstalled