UDP → HTTP/HTTPS Entry Point

This entry point accepts UDP traffic from an Air for Cellular device, encodes the content using Base64, and forwards the data to the forwarding destination as an HTTP request via HTTP or HTTPS, using strictly one UDP datagram per request.


Configuration

Entry Point

Your device should be configured to send UDP traffic to: beam.soracom.io:23080.

Parameters


Behavior

Request Behavior

Beam will encode the original message using Base64, and set the encoded content as the body of an HTTP POST request using JSON format.

{"payload": "<Base64-encoded-message>"}

Beam will also set the user agent string as SORACOM Beam in the HTTP request header.

Since the maximum transmission data size per message conforms to the maximum size of the UDP fragment, it is 65,536 bytes including the header.

Response Behavior

Since UDP has no request and response mechanism like HTTP, Beam will return a UDP packet to the device containing the HTTP response code and message received from the forwarding destination. The UDP packet message will use the following format: ${http-status-code} ${http-response-body}

When receiving the HTTP response code is not required, you can enable the Skip status code option in order to reduce data usage.


Example

Response example without body

echo "test message" | nc -v -u beam.soracom.io 23080
>found 0 associations
>found 1 connections:
>     1:    flags=82<CONNECTED,PREFERRED>
>  outif (null)
>  src 192.168.43.232 port 61852
>  dst 100.127.127.100 port 23080
>  rank info not available
>
>Connection to beam.soracom.io port 23080 [udp/*] succeeded!
>
>200

Response example with a body

echo "bad message" | nc -v -u beam.soracom.io 23080
>found 0 associations
>found 1 connections:
>     1:    flags=82<CONNECTED,PREFERRED>
>  outif (null)
>  src 192.168.43.232 port 61852
>  dst 100.127.127.100 port 23080
>  rank info not available
>
>Connection to beam.soracom.io port 23080 [udp/*] succeeded!
>
>400 Message from server

Advanced Configuration

The UDP → HTTP/HTTPS entry point can also be configured through the Soracom API or CLI by using the SoracomBeam namespace.

Configuration should be performed using udp://beam.soracom.io:23080 as the configuration key value.

Parameters

Sample

[
  {
    "key":"udp://beam.soracom.io:23080",
    "value": {
      "name": "udp2https",
      "destination": "https://beamtest.soracom.io/",
      "enabled": true,
      "addSubscriberHeader": true,
      "addSignature": true,
      "psk": "topsecret",
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      }
    }
  }
]