Skip to main content

Webhooks

Webhooks deliver every published event from a port as an outbound HTTP POST. Each port has its own list of webhook targets.

Managing webhooks​

GET    /api/ports/:path/webhooks
POST   /api/ports/:path/webhooks         { url, enabled?, events?, secret?, headers? }
PUT    /api/ports/:path/webhooks/:id     { ...partial }
DELETE /api/ports/:path/webhooks/:id

A webhook config is { id, url, events, secret, headers, enabled }:

  • url — where to POST.
  • events — an allow-list of event names. Empty means all events.
  • secret — if set, OmniBus signs the body (HMAC-SHA-256).
  • headers — extra headers to send (e.g. Basic auth).
  • enabled — toggle without deleting.

Delivery format​

When the adapter publishes an event, every enabled webhook whose events list is empty or includes that event name receives:

POST <webhook.url>
Content-Type: application/json
X-Omnibus-Port: /dev/ttyUSB0
X-Omnibus-Event: frame
X-Omnibus-Signature: sha256=<hmac of body using webhook.secret>   (if secret set)

{
  "port": "/dev/ttyUSB0",
  "event": "frame",
  "timestamp": 1731000000000,
  "payload": <event-specific JSON>
}

Reliability​

Failed deliveries are retried once with a 5-second timeout, then logged and dropped. Webhooks never block the serial bus — a slow or down endpoint can't back up the bus or other outputs.

Verifying the signature​

If you set a secret, verify X-Omnibus-Signature by computing HMAC-SHA-256(secret, rawBody) and comparing to the hex digest after the sha256= prefix. Reject anything that doesn't match.