> For the complete documentation index, see [llms.txt](https://docs.somewear.app/developer-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.somewear.app/developer-docs/beam/inbound-payloads.md).

# 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:

{% code title="\~/.config/somewear/beam.properties" %}

```bash
inbound-hook=echo $BEAM_PAYLOAD
```

{% endcode %}

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
```

{% code title="\~/bin/handle.py" %}

```python
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
```

{% endcode %}

#### 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:

```bash
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.

{% hint style="info" %}
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.
{% endhint %}

### Message

```json
{
  "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

```json
{
  "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

```json
{
  "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"
        }
      ]
    }
  ]
}
```