Publishing to Webhooks¶

The AirStack Edge API supports a flexible webhook system that allows external services to receive asynchronous callbacks when tasks complete or publish results. This is used for two primary workflows:

• Application Requests – When an application job finishes, Edge posts the received results to your registered endpoint.

• Recorded Rx Data – When a recording job finishes, Edge posts the raw recorded samples as an octet-stream, with accompanying sigmf metadata included in an HTTP header.

Webhooks allow your application or service to receive results without polling Edge or waiting for a long-running operation to complete.

Registering a Webhook Endpoint¶

To receive callbacks, clients must first register an endpoint using:

POST /webhooks/register

Registration Request Body
'{
  "authentication": "Bearer my-secret-random-string",
  "content_type": "json",
  "init_path": "http://url:port/api/setup/init",
  "init_payload": {
    "priority": 10,
    "task": "configure"
  },
  "name": "My Post Client",
  "post_path": "http://url:port/api/add_result"
}'

• name: A logical name for your client.
• content_type: Data format option (json, byte, discard)
• post_path: The full URL Edge will POST results to.

If an init_path and optional init_payload are provided Edge will first try to make a request to that initialization path when the webhook is registered. This can be used to initialize a new database or register the edge resource on the client. This is also a useful tool to test firewall configuration settings. If this POST fails an error will be returned to the user and the webhook will not be stored.

If registration succeeds, Edge will return a client_id:

Example Response
{
  "client_id": "b2fa1c79-6d3c-4c1e-932e-7b2eef119526"
}

This ID is used to manage (set or delete) your registered webhook for future requests.

Note: Webhook registrations do not currently persist across program restarts or device reboots. If AirStack Edge restarts, any configured webhooks are deleted and must be registered again.

Network and Firewall Considerations¶

Webhook communication is initiated by Edge. The URL configured in init_path or post_path must be reachable from the device running AirStack Edge, not just from the workstation or browser used to configure the webhook.

Firewall rules, routing, NAT, VPN settings, DNS configuration, proxy requirements, or blocked ports can prevent Edge from reaching the webhook receiver. When this happens, users will typically see timeout errors during webhook registration if init_path is configured, or timeout errors when Edge later attempts to publish results to post_path.

If a webhook request times out, verify that:

• The webhook host and port are reachable from the AirStack Edge device.
• The receiver service is listening on the configured interface and port.
• Host-based firewalls and network firewalls allow inbound traffic from the device and the application running the webhook code (likely python).
• The URL scheme, hostname, port, and path are correct.

Note: For users running webhook servers from Windows devices it will likely require Administrative priviledges to update Firewall settings

How Data Is Posted to Your Endpoint¶

Once a webhook is registered, Edge can be enabled to post the result of application or receive jobs to the configured endpoint. Depending on the type of request Edge posts are one of three types:

Application Results¶

Application module results posted to webhooks are formatted based on the webhook content_type: (json, byte, or discard).

• json: Edge sends application/json and converts the Triton output into a JSON value. String outputs that look like JSON are parsed, otherwise they are sent as strings. Byte outputs are sent as arrays of integer byte values. Float outputs are sent as arrays of numbers. Empty outputs will not be sent.

POST https://example.com/callback
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "prediction": "hello world",
  "confidence": 0.98
}

• byte: Edge sends application/octet-stream and forwards the raw output bytes. If raw bytes are not available, Edge serializes the parsed output (bytes as-is, float arrays as raw f32 bytes, strings as UTF-8). Empty outputs will not be sent..

POST https://example.com/callback
Content-Type: application/octet-stream
Authorization: Bearer <your-token>

<raw bytes>

• discard: Edge does not send a webhook POST for that result, this is mainly a debug option when using the client ui to monitor SSE responses.

Recorded Data (Binary + Metadata Header)¶

For recording tasks, Edge always posts the raw binary data as an application/octet-stream payload, ignoring the webhooks registered content-type.

POST https://example.com/callback
Content-Type: application/octet-stream
X-Metadata: <Json string>
Authorization: Bearer <your-token>
<raw binary sample data…>