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.

Versions

When using the Beam UDP → HTTP/HTTPS entry point, you may select between version 201509 and 202411. The differences between these versions are as follows.

Unified Endpoint Behavior

The Unified Endpoint behavior does not change based on the Platform Version selected for the UDP → HTTP/HTTPS entry point. If Unified Endpoint's Response Format is set to Soracom Beam, it will always operate based on Platform Version 202411.

The same behavior applies when the Response Format of Unified Endpoint is set to Auto (default) and only Soracom Beam is enabled in the group settings.

Error Responses

If the destination server returns an HTTP status code of 400 or higher, the TCP → HTTP/HTTPS entry point considers it an error response. In such cases, the response is transmitted to the device as the payload of a TCP packet, formatted according to the specifications defined by the platform version. As opposed to platform version 201509, platform version 202411 adds the the body of the HTTP response and removes the forwarding URL from the error response.

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.
• Client Certificate - The SSL/TLS client authentication configuration.
  • Use client cert - Enables the use of a client certificate for authentication.
  • Credentials set - The client certificate stored in Credential Sets to use for authentication.
• Platform version - Select the platform version to use. See Versions.
• 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.

For details on configuring and using header manipulations, refer to the Header Manipulation page.

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

• 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.
  • useClientCert (boolean, optional) - Enables or disables the use of an SSL/TLS client certificate for authentication.
  • clientCerts (object, optional) - The SSL/TLS client certificates to attach.
    • $credentialsId (string, optional) - ID of the credential set with the appropriate client certificate.
  • version (string, optional) - Defines the Beam platform version to use. If not defined platform version 202411 will be used.
  • 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
  • skipStatusCode (boolean, optional) - Whether to skip including the HTTP status code in the response to the device.
  • 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/",
      "version": "202411",
      "enabled": true,
      "addSubscriberHeader": true,
      "addSignature": true,
      "skipStatusCode": false,
      "psk": "topsecret",
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      }
    }
  }
]