GRPC

Services

EventService

The event API provides a mechanism for you to subscribe and publish events between your backend services and the composition, as well as receive events from the live and layout api.

Method Name	Request Type	Response Type	Description
Stream	EventsStreamRequest stream	EventsStreamResponse stream	Stream Events
Publish	PublishEventRequest	PublishEventResponse	Publish Event

Messages

EventTarget

Targetting for an event Event targetting allows you to listen or publish an event against a specific target. You can assume that: When subscribing, you will receive events for the chosen scope and any higher scope that isn't targetted. This means

• An event published against a layoutId can be listened to by targetting the given layoutId, projectId or collectionId
• An event published against a collectionId can be subscribed by scoping to any given projectId or layoutId under the collection.

Field	Type	Label	Description
collection_id	string	optional	Subscribe to events in a given collection.
project_id	string	optional	Subscribe to events in a given project.
layout_id	string	optional	Stream events to a specific layout. Note: when specified, collectionid and project_id are implictly defined. If you choose to define them, you they _must match the layout.

EventsStreamError

Indicates an error with a message sent to the Event API. Tie correlation_id on the message sent to the Event API and the correlation_id on the parent message to understand which request this error is for.

Field	Type	Label	Description
code	int32		The GRPC error code for the event.
message	string		A mesasage indicating what the error is.

EventsStreamReconnectRequest

Indicate to the client that they should re-open their connection

Field	Type	Label	Description
reauthenticate	bool		Whether the access token needs to be refreshed before reconnecting.
before_timestamp	string		A timestamp indicating when the connection should be reconnected by. If you're maintaining multiple connections, you should reconnect at a random interval within this time range.

EventsStreamRequest

Payload sent to the event API

Field	Type	Label	Description
correlation_id	string	optional	Optional value to tag any return values with. This can be any string-based value that your are able to track.
subscribe	SubscribePayload		Subscribe to a new event.
unsubscribe	SubscribePayload		Unsubscribe from an event.
publish	PublishEventRequest		Publish a new event.
ping	string		Initiate a ping-pong message.

EventsStreamResponse

Payload returned from the event API.

Field	Type	Label	Description
correlation_id	string	optional	Optional value to tag any return values with. Correlation ID should be used to correlate requests sent down the socket, enabling you to tie a PUBLISH to a `PUBLISHED``
session_id	string	optional	Optional session id This is set by sending the SessionId header for any HTTP requests and the sessionId query parameter for websockets.
event	PublishEventResponse		Custom event emitted
pong	string		Ping payload
error	EventsStreamError		Non-blocking streaming error
subscribed	SubscribePayload		Subscribe to a new event.
unsubscribed	SubscribePayload		Unsubscribe from an event.
published	PublishEventResponse		Publish a new event.
reconnect_before	EventsStreamReconnectRequest		Inform the client should reoconnect before a timestamp.

PublishEventRequest

Publish a custom event

Field	Type	Label	Description
name	string		Name of the event.
payload	google.protobuf.Struct		Value of the event. This can be a free-form value which we do not inspect.
request_metadata	google.protobuf.Value	optional	Metadata associated with the publishing of the event. Typically this is information about why the event happened. Use payload for what the event is.
target	EventTarget	optional	Scope the event to a specific target

PublishEventResponse

Response of an event being forwarded to a subscription. note: if this socket is also the publisher, this payload will be sent twice. Once for published and once for event. You can use correlation_id to identify the published event.

Field	Type	Label	Description
name	string		Name of the event.
payload	google.protobuf.Struct		Value of the event.
target	EventTarget	optional	Custom scoping parameters.
request_metadata	google.protobuf.Value	optional	Metadata associated with the publishing of the event
id	string		Internal ID of the event.

SubscribePayload

Payload to subscribe or unsubscribe from an event

Field	Type	Label	Description
name	string		Event name to subscribe to for custom events. This can be a wildcard my_service:* or multiple events `my_event
target	EventTarget	optional	The target to subscribe to.

Enums

EventsStreamMessageType

Name	Number	Description
EVENTS_STREAM_MESSAGE_TYPE_UNSPECIFIED	0
EVENTS_STREAM_MESSAGE_TYPE_PING	1
EVENTS_STREAM_MESSAGE_TYPE_ERROR	2
EVENTS_STREAM_MESSAGE_TYPE_SUBSCRIBED	3
EVENTS_STREAM_MESSAGE_TYPE_UNSUBSCRIBED	4
EVENTS_STREAM_MESSAGE_TYPE_PUBLISHED	5

Scalar Value Types (Reference)

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)