> ## Documentation Index
> Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events V1 overview

> Receive Batch Relay lifecycle facts as signed CloudEvents webhooks.

Batch Relay Events V1 is a push-only outbound webhook system. Each delivery is
one [CloudEvents 1.0](https://cloudevents.io/) 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](https://app.batchrelay.com/developers). 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:

```text theme={null}
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`](/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:

```json theme={null}
{
  "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](/events/receiving-webhooks) for signature verification
and [Versioning](/events/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](/events/topic-reference) and [complete
examples](/events/examples).