Soracom Beam

HTTP Entry Point

This entry point accepts HTTP requests from an Air for Cellular device and forwards the request to the forwarding destination via HTTP or HTTPS. You can create multiple HTTP entry point configurations, provided the path parameter is unique for each configuration.

---

Configuration

Entry Point

Your device should be configured to send data to: http://beam.soracom.io:8888/{my-custom-path}.

Parameters

• Configuration name (string, required) - A string to identify this configuration.
• Entry point - The HTTP entry point configuration.
  • Path (string, optional) - The URI path where Beam will accept data. This path is appended to the Beam HTTP entry point.
• 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.
  • 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.
  • Authorization header - Adds Authorization: {Parameter} to the HTTP request header.

Refer to the Header Manipulations documentation for additional details.

---

Behavior

Request Behavior

When Beam receives an HTTP request, it will close the original request and forward the request to the forwarding destination.

Response Behavior

When Beam receives an HTTP response from the forwarding destination, it will transfer the response directly to the device.

---

Example

$ curl -v -X POST -H 'Content-Type: application/json' -d '{"key":"value"}' http://beam.soracom.io:8888/
>*   Trying 100.127.127.100...
>* Connected to beam.soracom.io (100.127.127.100) port 8888 (#0)
>> POST / HTTP/1.1
>> Host: beam.soracom.io:8888
>> User-Agent: curl/7.49.0
>> Accept: */*
>> Content-Type:application/json
>> Content-Length: 15
>>
>* upload completely sent off: 15 out of 15 bytes
>< HTTP/1.1 200 OK
>< Content-Type: application/json
>< Date: Wed, 21 Dec 2016 02:25:01 GMT
>< Connection: close
>< Transfer-Encoding: chunked
><
>* Closing connection 0

---

Advanced Configuration

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

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

Parameters

• key (string, required) - http://beam.soracom.io:8888/
• 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, required) - Enables or disables adding subscriber information as a HTTP header or MQTT topic 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 (string, optional) - The Pre-Shared Key (passphrase) to be used when adding a signature header.

Sample

[
  {
    "key": "http://beam.soracom.io:8888/",
    "value": {
      "name": "My Beam config",
      "destination": "https://myserver.example.com/",
      "enabled": true,
      "addSubscriberHeader": true,
      "customHeaders": {
        "X-Group-Name": {
          "action": "replace",
          "headerKey": "X-Group-Name",
          "headerValue": "My header value"
        }
      },
      "addSignature": true,
      "psk": "my-secret-psk"
    }
  }
]