Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Publishing events to a Custom Event Bus

You publish events to a Custom Event Bus with one of two API operations, PutEvents or PutRawEvents. The operation that you choose fixes the shape of the delivered event, and that shape determines how you write every filter, transformer, and target parameter for the bus. Choose before you write your first subscriber. For the two shapes, see Event structure: data, metadata, and system metadata.

The two operations produce one kind of event, and EventBridge treats them identically once the event is on the bus. PutEvents is a convenience over PutRawEvents: EventBridge takes the entry's Source, DetailType, Detail, and other fields, builds a JSON envelope from them, and stores that envelope as a JSON payload with a content type of application/eventbridge+json. From then on, filtering, transformation, ordering, deduplication, retention, and delivery work exactly as they do for a JSON event published with PutRawEvents. The only difference a subscriber sees is where your fields sit: at the top of Data for PutRawEvents, and under Data.detail inside the envelope for PutEvents. For Avro, Protobuf, and opaque payloads, see Supported content types: JSON, Avro, Protobuf, and raw bytes.

Publish APIs

Both operations take a batch of 1 to 100 entries per request and return one result per entry, in request order. EventBridge accepts or rejects each entry on its own: a rejected entry carries an ErrorCode and ErrorMessage in place of a SuccessCode, and the other entries in the same request are unaffected. Batch entries that belong together, and read every result rather than the HTTP status alone; see Reading the response. Both calls draw from one publish rate budget for your account, and the bus itself has a per-second ingestion quota that counts every publisher and event source; see Custom Event Bus quotas.

Publish a JSON event with PutEvents

aws eventsv2 put-events \
    --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \
    --entries '[
        {
            "Source": "com.example.orders",
            "DetailType": "OrderPlaced",
            "Detail": "{\"orderId\":\"1001\",\"total\":42.5}"
        }
    ]'

Publish a raw event with PutRawEvents

Data is a binary field. In the Amazon CLI, supply it as base64 text. The following example publishes the same JSON payload as raw bytes with a content type of application/json, and adds a metadata key.

aws eventsv2 put-raw-events \
    --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \
    --entries '[
        {
            "Data": "eyJvcmRlcklkIjoiMTAwMSIsInRvdGFsIjo0Mi41fQ==",
            "Metadata": { "tenant": "acme" },
            "SystemMetadata": { "ContentType": "application/json" }
        }
    ]'

To publish Avro or Protobuf, name a schema registry in the request with --schema-registry-configuration. RegistryUri is an Amazon Glue Schema Registry ARN or a Confluent Cloud HTTPS URL. A registry is named per request, not on the bus. Events with a content type of application/octet-stream need no registry, because EventBridge does not decode them.

Publishing raw bytes

To publish a payload that EventBridge should neither parse nor inspect, call PutRawEvents with the bytes Base64-encoded in Data and SystemMetadata.ContentType set to application/octet-stream. EventBridge stores and delivers the bytes exactly as sent, so a DATA filter cannot match them; route them with METADATA keys you set on the entry or with SYSTEM_METADATA. A subscriber's transformer sees the payload as a Base64 string in $events.Data. For the delivery choices and the deserialized alternative for Avro and Protobuf, see Supported content types: JSON, Avro, Protobuf, and raw bytes; for how the payload appears to a transformer, see Transforming events with JSONata.

Reading the response

Both operations return one result for each entry, in the same order as the request. Each result carries either a SuccessCode or an ErrorCode and ErrorMessage. Check every entry, because a request can succeed while individual entries fail.

SuccessCode is PUBLISHED or DEDUPLICATED. DEDUPLICATED means that EventBridge recognized the entry as a duplicate of an event that it already accepted and did not store a second copy. It is a success, not an error. For more information, see Ordering and deduplicating events on a Custom Event Bus.

A publish response reports that EventBridge accepted the event. It does not report delivery. To confirm that an event arrived, check the target.

This section contains the following topics: