Events and message schema

You can configure event destinations for Stedi transaction enrollment events.

More event types, including transaction processing events, will be available in future releases. Please contact Stedi support to request event types for your use case.

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:

Header	Type	Description
attempt-number	integer	The delivery attempt number. The initial delivery is 1.
attempt-type	enum	Whether the attempt originated from Stedi (AUTOMATIC) or was a manual retry (MANUAL).
destination-id	string	The identifier for the event destination,formatted as dst_{UUID}.
event-id	string	The event identifier, formatted as evt_{UUID}.
webhook-id	string	A unique message identifier per the Standard Webhooks specification, formatted as msg_{UUID}. You can use this to check for duplicate event deliveries.
webhook-signature	string	A Stedi-generated signature, formatted as v1,{signature}. Use this to verify message authenticity.
webhook-timestamp	integer	A Unix timestamp indicating when the event was created. This is different from when the event was delivered. 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
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 Retrieve Event endpoint's eventPayload.v1Event object.

Events

You can subscribe to transaction enrollment events. You can also trigger a generic test event from within the Stedi portal to test your event destinations.

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 being credentialed with the payer. Customer support will contact 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.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 a new task is assigned, 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"
}

event.ping

A test event you can trigger to validate your event destination.

{
  "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"
}

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.