# Events

A Service MAY have an action that publishes events asynchronously. The Platform would subscribe to events and the Service will publish events back to the Platform.

Intended for webhooks, pubsub, user interactions and streaming IoT data.

# Example Event Pubsub

actions:
  user:
    help: Subscribe to user events
    events:
      signup:
        help: When a customer signs up
        http: &http
          port: 5000
          subscribe:
            path: /subscribe
            method: post
            contentType: application/json
          unsubscribe:
            path: /unsubscribe
            method: post
        output: &user
          type: object
          contentType: application/json
          properties:
            name:
              type: string
            email:
              type: string
      login:
        help: When a user logs in.
        http:
          <<: *http  # yaml magic to reuse the object declared above
        output: 
          <<: *user
      logout:
        help: When a user logs out.
        http:
          <<: *http
        output:
          <<: *user

1. Subscribe. The Platform subscribes to an event by making a HTTP request to the Service.

# Platform to Service
POST http://SERVICE/subscribe {
  "id": "9a8b0ad3-9bc0-4af5-890f-75b9acacf3ab",
  "event": "signup",
  "endpoint": "https://CLIENT/signups",
  "data": { }  # This would be a map of arguments if the event has any.
}

The Service MUST store this subscription information. Here's a Python snippet depicting this:

subscriptions = {}

def subscribe(data):
    subscriptions[data['id']] = data

2. Publish. A new event is ready to be published by the Service.

Here's a Python snippet which reads our previously declared subscriptions map:

def publish(event, data):
    for subscription in subscriptions:
        if subscription['event'] == event:
            # Make a HTTP POST request to subscription['endpoint']

The Service then makes a HTTP POST request to send the event to the Platform using the CloudEvents spec.

# Service to Platform
POST https://CLIENT/signups {
  "cloudEventsVersion" : "0.1",
  "eventType" : "com.user.signup",
  "source" : "/signup",
  "eventID" : "A234-1234-1234",
  "eventTime" : "2018-04-05T17:31:00Z",
  "contentType" : "text/json",
  "data" : {  # event data
    "name": "Steve",
    "email": "no-reply@microservice.guide"
  }
}

This allows the Platform to subscribe to many events. All subscriptions will have a unique destination to publish events.

# Overview

Example Services

Below are a few services that publish events.

• Slack: Bot
  • Listen and hear messages in a room.
• Twitter: Streaming tweets
  • Stream tweets filtered by a hashtag.

# Arguments

Subscribing to an event MAY include arguments which can be used to define certain parameters concerning the subscription. For example, filtering the content before the event is published.

See Action Arguments for details.

# Output

The event published to the Platform MUST include the output detailing the structure of the event data published.

See Action Output for details.