Set up Webhooks

Receive signed JSON events from octoja at your own HTTPS endpoint.

Written By Stefan Steuer

Last updated 26 days ago

A webhook is an HTTP POST that octoja sends to a URL you control. Every delivery is a signed JSON request, so your receiver can verify that it really came from octoja. Use webhooks to feed octoja events — test deliveries you trigger yourself and asset-inventory pushes — into your own services and automations.

Prerequisites

  • You need the Integration Management permission. It lets you create, edit, and delete webhooks for the tenant. Permissions are assigned under Administration → Groups.
  • You need a publicly reachable URL that accepts HTTPS POST requests with a JSON body — for example an HTTPS handler in your own service or an automation platform endpoint.

Steps

  1. Go to Administration → Integrations and click Manage webhooks on the Webhooks card.
  2. Click Add Webhook.
  3. Fill in the dialog:
FieldDescription
NameDisplay label for this webhook. Free text — pick something that identifies the receiver (e.g. "PagerDuty alerts")
URLThe HTTPS endpoint octoja will POST events to. Must be a publicly reachable HTTPS URL.
Add Webhook dialog with a Name field, a URL field, and the Create button.
  1. Click Create. octoja generates a signing secret and shows it once in the Save your webhook secret dialog. Copy it now — you cannot view it again later. Store it in your receiver's configuration as the HMAC verification key, then click I've saved it. octoja takes you straight to the new webhook's detail page.
  2. Enable the webhook. New webhooks are created in the Disabled state and deliver nothing until you switch them on. Flip the toggle at the top of the detail page so the status next to it reads Active.
  3. Click Send test in the page header to deliver a synthetic test event to your endpoint, then open the History tab to confirm the delivery succeeded (status, response code, and duration are shown per attempt).

That's it — the webhook is active and verified. The sections below cover the wire format your receiver must handle and the day-2 operations (replay, secret rotation, retries).

Which events octoja sends

Each delivery names its event type in the X-Octoja-Event header:

EventFires when
WebhookTestYou click Send test on the webhook's detail page. Delivered even while the webhook is disabled, so you can verify your receiver before going live
InventorySnapshotA full asset-inventory baseline (customers, sites, devices, hardware) is pushed when inventory delivery starts for a webhook
InventoryUpdateAn hourly batch of inventory changes since the last push — updated devices, removed devices, and the current customer list
CheckFailedA monitoring check trips its alert threshold and reports a critical result. Delivered when the webhook is selected as an alert channel on that check
CheckWarningA monitoring check trips its alert threshold and reports a warning result. Delivered when the webhook is selected as an alert channel on that check
CheckRecoveredA monitoring check that previously alerted clears again. Delivered when the webhook is selected as an alert channel on that check
automationAn automation workflow reaches a step that sends to this webhook. Delivered when the webhook is the target of an automation's send-webhook step

The Events column on the Webhooks list page shows which events each webhook is subscribed to for inventory delivery. Newly created webhooks start without an inventory subscription, and the current version does not offer a control to change it — test deliveries and replays work regardless. The check-monitoring events (CheckFailed, CheckWarning, CheckRecovered) and the automation event do not depend on that subscription: they arrive whenever the webhook is picked as an alert channel on a monitoring check or as the target of an automation step. Build your receiver to dispatch on the X-Octoja-Event header and ignore event types it does not recognize.

Request format

Each delivery is a single HTTPS POST with a JSON body. The request carries these headers:

HeaderValue
X-Octoja-EventThe event type — for example WebhookTest
X-Octoja-DeliveryA unique GUID identifying this delivery. Use it for idempotency on your side
X-Octoja-TimestampUnix seconds when the request was signed. Always within a few seconds of "now"
X-Octoja-Signaturesha256=<hex> — HMAC-SHA256 over the string {timestamp}.{body} using your webhook secret
User-Agentoctoja-Webhooks/1.0
Content-Typeapplication/json

Verifying the signature

Always validate X-Octoja-Signature before trusting the payload. The signature is the HMAC-SHA256 of the literal string <timestamp>.<body> (with a dot separator) computed using your webhook's secret.

Node.js example:

const crypto = require('crypto');const secret = process.env.OCTOJA_WEBHOOK_SECRET;const timestamp = req.header('X-Octoja-Timestamp');const signature = req.header('X-Octoja-Signature'); // "sha256=..."const rawBody = req.rawBody.toString('utf8');const expected = 'sha256=' + crypto  .createHmac('sha256', secret)  .update(`${timestamp}.${rawBody}`)  .digest('hex');if (signature !== expected) return res.status(401).end();

Always compare the signature using a constant-time comparison (crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python) to avoid timing-side-channel leaks.

Retry and auto-disable

If the receiver responds with a non-2xx status or the request times out, octoja retries automatically:

AttemptDelay after the previous attempt
21 minute
35 minutes
430 minutes
52 hours
612 hours
724 hours
  • A response in the 4xx range (Unauthorized, Bad Request, Not Found, etc.) is treated as a permanent receiver problem and is not retried — the delivery is dead-lettered immediately.
  • A response in the 5xx range, a network error, or a 10-second per-attempt timeout triggers the retry schedule.
  • After 20 consecutive failed deliveries, the webhook is automatically disabled. You see this on the list page (the status indicator next to the name) and on the detail page (the toggle shows Disabled). Fix the receiver, then switch the toggle back on to resume delivery.

Testing the receiver

On a webhook's detail page, click Send test to deliver a synthetic WebhookTest event right now. Use this to verify your endpoint is reachable, the URL is correct, and the signature verification works.

Test events bypass the enabled toggle (so you can test a disabled webhook) and do not count toward the auto-disable threshold (so testing against a broken URL cannot disable your own webhook).

Replaying a past delivery

The History tab on the detail page lists the delivery attempts of the last 30 days with their event, status, attempt number, and duration, and lets you filter by event type, status, and time range. Click Replay on a delivery to re-send the original request body to your endpoint. Useful when your receiver was temporarily down and you want to push the missed events through manually.

Rotating the secret

If a secret leaks, open the webhook's detail page and click Rotate secret on the Configuration tab. Confirm the Rotate signing secret? dialog — octoja generates a new secret and shows it once in a reveal dialog, the same way it did on creation. Copy it before closing the dialog, because it cannot be displayed again.

The dialog mentions a 24-hour transition window for the old secret. Plan the rotation as a cutover anyway: switch your receiver to the new secret immediately after confirming, because every delivery octoja signs from that point on uses the new key.

Tips

  • Custom headers — the Custom headers card on the Configuration tab holds fixed headers that octoja sends with every delivery (for example a static API token). They are sent verbatim alongside the X-Octoja-* headers and are not part of the signature computation.
  • Idempotency — use X-Octoja-Delivery as an idempotency key on your side. If a retry succeeds after the original attempt timed out, you will see the same delivery ID twice.
  • Replay protection — discard requests whose X-Octoja-Timestamp is more than 5 minutes old to limit replay risk.
  • Troubleshooting: if deliveries never arrive, first check that the webhook is Active — new webhooks start disabled. Then click Send test to surface the exact response octoja receives, verify your receiver returns 2xx (any 4xx fails permanently), and check Product Status & Known Limitations.

See also: Send Alerts to a Microsoft Teams Channel — post octoja notifications into a Teams channel via Power Automate.