Inbound Payloads

When Beam receives a payload from Somewear, it can forward the data with two different methods: a script or a webhook.

Configure a Beam Script Hook

You can have Beam run a script whenever it receives an inbound payload. Similar to webhooks, the payload will be sent to your script as a JSON. Your script can access the JSON data from stdin or BEAM_PAYLOAD environment variable. Beam will print your script's stdout.

To configure a Beam script hook, you need to add an inbound-hook key-value pair to your beam.properties file:

~/.config/somewear/beam.properties

inbound-hook=echo $BEAM_PAYLOAD

The sample script above echo $BEAM_PAYLOAD will simply print the JSON payload. If you'd like to do something else, simply edit the beam.properties file and rerun beam up.

Examples

Run Python Script

inbound-hook=python ~/bin/handle.py

~/bin/handle.py

import json
import sys

# Read each line from stdin
for event_string in sys.stdin:
    
    # Parse json string to event that we can handle
    event = json.loads(event_string)
    
    # Pretty print object as json
    print(json.dumps(event, indent=2))
    
    # TODO: handle event

Write inbound payloads to file

inbound-hook=tee -a /tmp/beam-data.txt

Echo JSON messages to Slack

inbound-hook=curl -d "text=$BEAM_PAYLOADD" -d "channel=<YOUR_CHANNEL>" -H "Authorization: Bearer <SLACK_API_KEY>" -X POST https://slack.com/api/chat.postMessage

Configure a Beam Webhook

Like our cloud webhooks, Beam webhooks make a POST request to a URL of your choosing. This is done by configuring Beam with a webhook. For example, if you had a local web server running alongside Beam, you could configure Beam webhook with http://localhost:8080/somewear and your web server will start receiving Beam traffic at that endpoint.

To configure a Beam webhook you need to add a webhook-address key-value pair to your beam.properties file:

echo "webhook-address=<YOUR_BEAM_WEBHOOK_URL>" >> ~/.config/somewear/beam.properties

If you'd like to quickly test this out without standing up a web server yourself, try out https://webhook.site/.

JSON Format

Beam script hooks and webhooks will receive data in the following format. The JSON format is designed to match the cloud-based webhooks.

Although payload and events are arrays, you can safely assume that you'll only receive one element for each. If we do upgrade Beam to support batching and this changes, it will require an opt-in flag.

Message

{
  "requestId": "66ef6f9b-8870-4e18-99e1-f14ee7eae91d",
  "payloads": [
    {
      "identity": {
        "id": "0",
        "name": "Example User",
        "type": "User",
        "email": "[email protected]"
      },
      "account": {
        "id": "0"
      },
      "events": [
        {
          "type": "Message",
          "content": "Hello from space!",
          "timestamp": "2023-04-12T19:15:14Z"
        }
      ]
    }
  ]
}

Location

{
  "requestId": "66ef6f9b-8870-4e18-99e1-f14ee7eae91d",
  "payloads": [
    {
      "identity": {
        "id": "0",
        "name": "Example User",
        "type": "User",
        "email": "[email protected]"
      },
      "account": {
        "id": "0"
      },
      "events": [
        {
          "type": "Location",
          "latitude": "37.781001",
          "longitude": "-122.393456",
          "timestamp": "2023-04-12T19:15:14Z"
        }
      ]
    }
  ]
}

Data

{
  "requestId": "fe06b693-af2e-49da-963b-97fddaaa97eb",
  "payloads": [
    {
      "identity": {
        "id": "0",
        "name": "Example User",
        "type": "User",
        "email": "[email protected]"
      },
      "account": {
        "id": "0"
      },
      "events": [
        {
          "type": "Data",
          "payload": "VGVzdAo=",
          "timestamp": "2023-04-12T18:56:32Z"
        }
      ]
    }
  ]
}