Change Events
Recommendation
Updated
Moved
USE
2023-10-10
What is it
Change events are used to communicate the complete new state of a resource.
Why we use it
To be able to act on any change, for example to create an audit log.
When to use it
Typically only when the producer and consumer are within the same system, as it otherwise requires the consumer to apply logic to conclude what happened with the resource, and guess the reason for it. This event can be seen as an opposite to an domain event.
It is recommended to use the outbox pattern to guarantee consistency and at-least-once delivery.
Example event:
// Event capturing a mutation of a shipment (create / update / delete).
message ShipmentChangedEvent {
// UUIDv4 of the event.
string event_id = 1;
// Database transaction timestamp.
google.protobuf.Timestamp event_time = 2;
// Trace ID of the request that emitted this event. This field can be empty.
string trace_id = 3;
// All the IAM members of the caller that mutated the resource.
repeated string iam_members = 4;
// The updated value of the shipment.
Shipment shipment = 5;
}