Posting events

crispymtn/zaikio-loom-ruby

Post events to loom in a background job

Applications publish events to Loom by posting to Loom's RESTful JSON API.

The application needs to authenticate with its name and password via HTTP Basic Auth – both can be found in the Zaikio Hub. Furthermore, each message needs to include the following pieces of information:

Name	Required	Description
id	Required	The unique UUID of this event. Loom will reject UUIDs which are not unique. It helps subscribers noticing messages that have been delivered multiple times
timestamp	Required	The ISO8601 timestamp when the event happened. Besides Loom will generate a received_at timestamp and include it into the pushed message
name	Required	A name is generated by joining the application's name and the event's name with a dot – both can be found in the Zaikio Hub. Example: zaikio.user_created
subject	Required	The type and id of the subject in which context the event was triggered. Example: Org/2b271d51-e447-4a16-810f-5abdc596700a
version	Required	The version of the payload's format and structure. The application's developer documentation should include a section about all fired events and their payload.
payload	optional	The payload of the event following the description below
link	optional	An API URL that provides more information about this event

The Subject

The subject identifies the Person or the Organization in which domain the event was triggered. Based on the subject Loom will determine the list of Apps to which it will deliver the event.

The subject must be connected to the App that send sends the event. The event will be send to all Apps that:

• are interested in this event type,
• are connected to the subject and
• have been granted access for the specific event type.

The format for an subject is the same as a bearer, example: Org/2b271d51-e447-4a16-810f-5abdc596700a. See Bearer Type and ID.

Payload Requirements

The event's payload needs to fulfill a few requirements to ensure efficient message delivery and a consistent interface for the receiving applications:

• the payload must be a hash
• keys must be strings formatted in lowercase snake_case
• its serialized JSON size must be smaller than 256 bytes

Please note that applications publishing events cannot control the list of subscribing applications. Therefore, do not include any information in the payload which is considered private, sensitive or might be regulated by the General Data Protection Regulation law. Only include pieces of information that allow the subscribing application to understand if the message is relevant and which enables the receiver to load additional information via the application's API.

Best Practices

Imaging user signup. This event should not include any personal data like a name or an email address. Instead, it would just include the user's identifier. This information is sufficient for the receiving application to load additional information about the user when the application or the user has the required access rights.

{
  "name": "app_name.user_created",
  "payload": {
    "user_id": "9c31b099-e28a-42c8-86b4-d4fddd3512c6"
  }
  ...
}

Sometimes it might makes sense to have more details in the payload to help subsribers understanding the relevance before loading additional data. But even in this case keep the payload small and do not include personal or sensitive data.

{
  "name": "app_name.role_added",
  "payload": {
    "new_role": "administrator",
    "user_id": "9c31b099-e28a-42c8-86b4-d4fddd3512c6",
    "organization_id": "76705b00-cee0-4e50-bab6-93e684825ea5"
  }
  ...
}