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.

Message

{
  "requestId": "66ef6f9b-8870-4e18-99e1-f14ee7eae91d",
  "payloads": [
    {
      "identity": {
        "id": "0",
        "name": "Example User",
        "type": "User",
        "email": "example@example.com"
      },
      "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": "example@example.com"
      },
      "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": "example@example.com"
      },
      "account": {
        "id": "0"
      },
      "events": [
        {
          "type": "Data",
          "payload": "VGVzdAo=",
          "timestamp": "2023-04-12T18:56:32Z"
        }
      ]
    }
  ]
}

Last updated