Events V1 overview - Batch Relay API

Batch Relay Events V1 is a push-only outbound webhook system. Each delivery is one CloudEvents 1.0 structured JSON document in one HTTP POST. There is no Batch Relay wrapper around the CloudEvent. Configure destinations and select available topics in the Developer Dashboard. The dashboard also shows delivery history and any topic references available to your account.

Contract authority

The live AsyncAPI document is the canonical public event contract:

https://api.batchrelay.com/asyncapi.json

This documentation site renders deterministic reference material from the public Events V1 contract. Its checked-in snapshot is available at /specs/events-v1.asyncapi.json, but an integration should retrieve or pin the live canonical document for release validation.

Direct CloudEvent payload

Every request has Content-Type: application/cloudevents+json and a JSON body like this:

{
  "specversion": "1.0",
  "id": "evt_order_demo_01JQ8Y5Q8K6H9W2M4R7T1V3X5Z",
  "source": "https://api.batchrelay.com/event-sources/studios/stu_demo_01JQ8Y3A2B4C6D8E0F1G2H3J4",
  "type": "order.created.v1",
  "subject": "orders/ord_demo_01JQ8Y4K5M6N7P8Q9R0S1T2U3",
  "time": "2026-08-16T18:42:31.123Z",
  "datacontenttype": "application/json",
  "dataschema": "https://api.batchrelay.com/schemas/events/order.created/v1",
  "tenanttype": "studio",
  "tenantid": "stu_demo_01JQ8Y3A2B4C6D8E0F1G2H3J4",
  "environment": "sandbox",
  "origin": "storefront",
  "resourceversion": 1,
  "correlationid": "cor_demo_order_01JQ8Y2Z3A4B5C6D7E8F9G0H1",
  "actorkind": "system",
  "data": {
    "order_id": "ord_demo_01JQ8Y4K5M6N7P8Q9R0S1T2U3",
    "status": "created",
    "currency": "USD",
    "subtotal_minor_units": 5000,
    "discount_minor_units": 0,
    "shipping_minor_units": 499,
    "tax_minor_units": 350,
    "total_minor_units": 5849,
    "lines": [
      {
        "line_id": "lin_demo_01JQ8Y6R7S8T9U0V1W2X3Y4Z5",
        "package_id": "pkg_demo_01JQ908M0N1P2Q3R4S5T6U7V8",
        "display_name": "Varsity Portrait Package",
        "quantity": 1,
        "unit_price_minor_units": 5000
      }
    ]
  }
}

The envelope answers what happened, where, and when. data carries the topic-specific business fact. origin identifies how the fact entered Batch Relay (storefront, developer_api, or system); it is not a transport channel. When an event defines monetary summary fields, all five components are present: subtotal_minor_units, discount_minor_units, shipping_minor_units, tax_minor_units, and total_minor_units. Values are non-negative integers in USD; an inapplicable component is 0, not omitted.

Delivery semantics

Delivery is asynchronous and at least once. A receiver can see the same CloudEvent more than once.
A 2xx response acknowledges the delivery. Any other response, timeout, or network failure is eligible for retry.
Retry timing and delivery history are available in the Developer Dashboard; do not rely on an assumed retry schedule.
Events may arrive out of order. Use time, resourceversion, and your own durable state rules rather than arrival order.
One HTTP request contains one CloudEvent. Batch delivery is not part of V1.

See Receiving webhooks for signature verification and Versioning for compatibility rules.

Public event catalog

This public reference intentionally lists only public topics. Topics that need additional account capabilities are documented only in the authenticated Developer Dashboard, and operator-only topics do not appear in customer-facing documentation. See the topic reference and complete examples.

​Contract authority

​Direct CloudEvent payload

​Delivery semantics

​Public event catalog

Contract authority

Direct CloudEvent payload

Delivery semantics

Public event catalog