Soracom Beam

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

• Configuration name (string, required) - A string to identify this configuration.
• Destination - The forwarding destination.
  • Protocol (HTTP or HTTPS, required) - The protocol to use for forwarding HTTP requests.
  • Host name (string, required) - The FQDN of the forwarding destination.
  • Port number (number, required) - The port number of the forwarding destination.
  • Path (string, optional) - The URI path to use for forwarding HTTP requests.
• Header manipulations - Operations to perform on the HTTP request headers.
  • IMSI header - Adds X-Soracom-IMSI: {IMSI} to the HTTP request header.
  • SIM ID header - Adds X-Soracom-SIM-ID: {SIM_ID} to the HTTP request header.
  • MSISDN header - Adds X-Soracom-MSISDN: {MSISDN} to the HTTP request header.
  • IMEI header - Adds X-Soracom-IMEI: {IMEI} to the HTTP request header.
  • Signature header - Adds X-Soracom-Signature: {Signature} to the HTTP request header. This option requires IMSI header or IMEI header to be enabled in order to generate the signature.
  • Pre-Shared Key - The key to use when generating the Signature header.
  • Custom headers - Additional options for adding, modifying, or removing headers from HTTP requests before they are forwarded to the destination.
• Response - Configure response behavior.
  • Skip status code (optional) - When enabled, Beam will not return a status code to the device.

---

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.

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

• key (string, required) - udp://beam.soracom.io:23080
• value (object, required) - The configuration parameters.
  • name (string, optional) - Name to identify this configuration.
  • destination (string, required) - URL of the forwarding destination.
  • enabled (boolean, required) - Enables or disables the configuration.
  • addSubscriberHeader - (boolean, optional) - Enables or disables adding the subscriber IMSI as an HTTP header in the forwarded request.
  • addSimIdHeader - (boolean, optional) - Enables or disables adding the SIM ID as an HTTP header in the forwarded request.
  • addMsisdnHeader - (boolean, optional) - Enables or disables adding the SIM MSISDN as an HTTP header in the forwarded request.
  • customHeaders (object, optional) - Defines custom headers behavior. Each custom header is defined using:
    • X-Header-Name (string, required) - Name of the custom header.
      • action (string, required) - Defines the header behavior using one of the following values:
        • append - Appends the defined header to the HTTP request.
        • replace - Replaces any existing header with the defined header value.
        • delete - Deletes the header from the HTTP request.
      • headerKey (string, required) - The header name.
      • headerValue (string, required) - The header value.
  • addSignature (boolean, required) - Enables or disables adding a signature header for subscriber verification
    • psk.$credentialsId (string, optional) - The ID assigned to the pre-shared key credential set. Used for signing when addSignature is set as true. This ID is set when the credential is registered in the Credentials Store.

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