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.

Forms, event media, and import attempts

Form definitions describe the questions a Studio collects. form.created.v1, form.updated.v1, and form_revision.published.v1 describe authoring and publication. Form response topics describe a committed submission or edit to answers. Their actor and submission method identify whether a guardian, staff member, or API performed the operation. They do not identify the purchaser or include answer values. There are no form archive, delete, or restore topics. event.updated.v1 reports safe event metadata changes. photo_assignment.updated.v1 reports changes to portrait or team-photo assignment using opaque resource references. They contain no child names, contact details, image URLs, or form answers. Image import completion means the intended media assignment was committed. An upload alone is not completion. A failed attempt records its stage, such as upload or commit, and its retryable flag. A retryable failure can be followed by a successful committed completion. Treat each event as a lifecycle fact, not a final judgment on the whole import session. These topics require the matching account capability and destination subscription. Their schemas and examples are available in the authenticated Developer Dashboard.

Fulfillment progress and completion

order.fulfillment_updated.v1 reports changes to the digital, lab, and Studio fulfillment components. Consumers can track a mixed order without treating the first successful component as completion of the entire order. order.fulfilled.v1 means every required component finished successfully. Digital completion requires successful delivery to the customer. Preparing a file or sending a debug preview does not qualify. Lab completion requires the recorded shipment milestone. Studio completion requires the recorded handoff or shipment milestone. Shipment and handoff are not proof of arrival at the customer’s address. A digital-only order completes after successful digital delivery; a mixed order also waits for its required physical components.

Purchaser context

Core storefront order events may carry an opaque buyer_ref. The purchaser is separate from actorkind, which can be system for payment confirmation. A guest reference is scoped to that transaction. An account reference is scoped to the Studio and does not expose a guardian or authentication identifier. Names and email addresses are retrieved through a separately authorized API request. They are never added to the universal event payload. See Purchaser context for explicit Studio opt-in, API key permissions, and guest handling.

​Contract authority

​Direct CloudEvent payload

​Delivery semantics

​Public event catalog

​Forms, event media, and import attempts

​Fulfillment progress and completion

​Purchaser context