asyncapi: 2.6.0 info: title: CloudEvents HTTP Delivery description: >- AsyncAPI definition for CloudEvents delivery over HTTP. This document describes the event-driven interface by which a CloudEvents-compatible broker pushes events to a subscriber's HTTP sink endpoint. Events are formatted as CloudEvents v1.0 and delivered in either structured content mode (application/cloudevents+json) or binary content mode (with CloudEvents attributes in HTTP headers). The subscriber's endpoint acts as an HTTP webhook that receives POST requests from the event broker. version: '1.0' contact: name: CloudEvents Community url: https://cloudevents.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 externalDocs: description: CloudEvents HTTP Protocol Binding Specification url: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md servers: subscriberSink: url: '{sinkUrl}' protocol: https description: >- The subscriber's HTTP sink endpoint where the event broker delivers CloudEvents. Provided by the subscriber when creating a subscription. variables: sinkUrl: description: >- Fully qualified HTTPS URL of the subscriber's event receiver endpoint, as registered in the CloudEvents Subscriptions API. security: - bearerAuth: [] channels: /: description: >- The subscriber's sink endpoint receives HTTP POST requests from the CloudEvents broker. Each request carries one CloudEvent (single delivery mode) or a batch of CloudEvents (batch delivery mode). The subscriber acknowledges receipt with a 2xx HTTP response. publish: operationId: receiveCloudEvent summary: Receive a CloudEvent from the broker description: >- The event broker delivers a CloudEvent to this endpoint via HTTP POST. In structured content mode the Content-Type is application/cloudevents+json and the full event including context attributes is in the request body. In binary content mode event context attributes are mapped to HTTP headers prefixed with 'ce-' and the data payload is the raw request body with the event's datacontenttype as Content-Type. message: oneOf: - $ref: '#/components/messages/StructuredCloudEvent' - $ref: '#/components/messages/BinaryCloudEvent' - $ref: '#/components/messages/BatchedCloudEvents' /batch: description: >- Batch delivery endpoint where the broker delivers multiple CloudEvents in a single HTTP POST request using the application/cloudevents-batch+json content type. Reduces per-event HTTP overhead for high-throughput scenarios. publish: operationId: receiveCloudEventBatch summary: Receive a batch of CloudEvents from the broker description: >- The event broker delivers multiple CloudEvents in a single HTTP POST request using the application/cloudevents-batch+json media type. The body is a JSON array where each element is a complete CloudEvent in structured format. The subscriber should return 200 to acknowledge successful receipt of the entire batch. message: $ref: '#/components/messages/BatchedCloudEvents' components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token authentication for the subscriber sink endpoint. The event broker includes this token in the Authorization header when delivering events. Configure via protocolSettings in the subscription. messages: StructuredCloudEvent: name: StructuredCloudEvent title: CloudEvent (Structured Content Mode) summary: >- A single CloudEvent delivered in structured content mode where all event data including context attributes is encoded as a JSON object in the HTTP request body. contentType: application/cloudevents+json headers: type: object properties: Content-Type: type: string const: application/cloudevents+json description: >- Indicates structured CloudEvents content mode. The full CloudEvent is in the HTTP body as a JSON object. payload: $ref: '#/components/schemas/CloudEvent' BinaryCloudEvent: name: BinaryCloudEvent title: CloudEvent (Binary Content Mode) summary: >- A single CloudEvent delivered in binary content mode where CloudEvents context attributes are HTTP headers prefixed with 'ce-' and the event data is the raw HTTP body. headers: type: object required: - ce-specversion - ce-id - ce-source - ce-type properties: ce-specversion: type: string const: '1.0' description: CloudEvents spec version header. Always '1.0'. ce-id: type: string description: Unique identifier for the event. Corresponds to the 'id' attribute. ce-source: type: string description: URI-reference identifying the event origin. Corresponds to 'source'. ce-type: type: string description: Type of the event. Corresponds to the 'type' attribute. ce-subject: type: string description: Subject of the event in the producer context. Corresponds to 'subject'. ce-time: type: string format: date-time description: RFC 3339 timestamp of when the event occurred. Corresponds to 'time'. ce-dataschema: type: string format: uri description: URI of the schema the data adheres to. Corresponds to 'dataschema'. ce-traceparent: type: string description: W3C Trace Context traceparent for distributed tracing extension. ce-tracestate: type: string description: W3C Trace Context tracestate for distributed tracing extension. Content-Type: type: string description: >- MIME type of the event data payload. Corresponds to the 'datacontenttype' CloudEvents attribute. payload: description: >- The raw event data payload. Its structure is defined by the event type and the schema identified by the ce-dataschema header. BatchedCloudEvents: name: BatchedCloudEvents title: CloudEvents Batch summary: >- A batch of CloudEvents delivered in a single HTTP POST using the application/cloudevents-batch+json media type. Improves throughput by reducing per-event HTTP overhead. contentType: application/cloudevents-batch+json headers: type: object properties: Content-Type: type: string const: application/cloudevents-batch+json description: >- Indicates batch CloudEvents content mode. The body is a JSON array of CloudEvent objects. payload: type: array description: JSON array of CloudEvent objects in structured format. items: $ref: '#/components/schemas/CloudEvent' minItems: 0 schemas: CloudEvent: type: object description: >- A CloudEvents v1.0 event envelope with required context attributes and optional data payload. required: - specversion - id - source - type properties: specversion: type: string const: '1.0' description: CloudEvents specification version. id: type: string description: >- Unique identifier for this event, unique within the scope of the producer. source: type: string description: URI-reference identifying the context in which the event occurred. type: type: string description: >- Reverse-DNS-prefixed string identifying the event type, e.g. com.example.object.created. datacontenttype: type: string description: RFC 2046 media type of the event data. dataschema: type: string format: uri description: URI of a schema the data attribute adheres to. subject: type: string description: Subject of the event within the producer context. time: type: string format: date-time description: Timestamp of when the event occurrence happened. data: description: Event-specific payload data. Structure defined by the event type. data_base64: type: string contentEncoding: base64 description: Base64-encoded binary event data, mutually exclusive with 'data'.