When Beam receives a payload from Somewear, it can hand the data to a script or push it to a webhook — your choice.

Run a script on every inbound payload

Beam can run a script every time it receives a payload. Your script gets the payload as JSON, either on stdin or in the BEAM_PAYLOAD environment variable. Beam prints whatever your script writes to stdout.

Add an inbound-hook entry to your beam.properties file:

inbound-hook=echo $BEAM_PAYLOAD

That example just prints the payload. Point it at your own script instead:

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

# ~/bin/handle.py
import json
import sys

for event_string in sys.stdin:
    event = json.loads(event_string)
    print(json.dumps(event, indent=2))
    # handle the event here

A couple more examples:

# Append every payload to a file
inbound-hook=tee -a /tmp/beam-data.txt

# Post payloads into a Slack channel
inbound-hook=curl -d "text=$BEAM_PAYLOAD" -d "channel=<YOUR_CHANNEL>" -H "Authorization: Bearer <SLACK_API_KEY>" -X POST https://slack.com/api/chat.postMessage

Push inbound payloads to a webhook

Beam can also POST inbound payloads to a URL of your choosing — the same idea as Somewear’s cloud webhooks, but routed through your Beam instance instead of the internet.

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

Note

No server handy to test against? webhook.site gives you a disposable URL that shows you every request it receives.

Payload format

Script hooks and webhooks receive the same JSON shape Somewear’s cloud webhooks use.

Note

payloads and events are arrays, but you’ll only ever see one element in each today. If Beam adds batching later, it’ll be behind an opt-in flag — this shape won’t change under you.

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"
        }
      ]
    }
  ]
}