Skip to the content

DocumentationWebhooks

Connect your systems

Webhooks

Signed calls to your own systems

OpsCommand tells your systems, Slack or Microsoft Teams when something happens in your organisation: an alert opens or closes, an incident is proposed or opened, someone is paged or acknowledges a page (PLAN 4.11). Endpoints are set up under Organisation Administration → Integrations by someone with integrations.manage.

What arrives

POST to your address, Content-Type: application/json, with these headers:

HeaderWhat it is
OpsCommand-EventThe event: alert.opened, alert.resolved, incident.proposed, incident.opened, page.opened, page.acknowledged (and webhook.ping when someone sends a test).
OpsCommand-DeliveryThis delivery's id (a UUID). The same delivery retried carries the same id.
OpsCommand-VersionThe payload's version, today 2026-11-06. A changed payload gets a new version; fields are only ever added within one.
OpsCommand-Signaturet=<unix seconds>,v1=<hex> — HMAC-SHA256 of <t>.<raw body> with your signing secret; two v1= while a rotated secret overlaps.

The body:

{
  "id": "<the delivery id>",
  "type": "alert.opened",
  "version": "2026-11-06",
  "occurredAt": "2026-11-06T13:00:00.000Z",
  "organisation": "your-organisation",
  "data": {
    "alert": { "id": "…", "title": "Checks failing: Payment API", "severity": "critical", "source": "monitor", "status": "open" },
    "service": { "id": "…", "key": "payments", "name": "Payment integration" },
    "path": "services/payments",
    "link": "https://app.opscommand.dev/o/your-organisation/services/payments"
  }
}

data holds alert, incident (with its reference, e.g. INC-12), proposal or page according to the event, the service where there is one, and a link into OpsCommand. It never carries anyone's contact details; a person is named by their display name only.

Verifying a delivery

  1. Take the raw body exactly as received (before parsing it).
  2. From OpsCommand-Signature, read t and every v1.
  3. Refuse it if t is more than 5 minutes from your clock.
  4. Compute HMAC-SHA256 of "<t>.<raw body>" with your secret; accept if it equals one v1 (compare in constant time).
  5. Refuse a delivery id you have already accepted (replay protection); keep accepted ids for at least a day.
  6. Answer 2xx within 10 seconds; do the work afterwards.

In Node.js, @opscommand/crypto has it ready:

import { webhookRefusal } from '@opscommand/crypto';
const refusal = webhookRefusal(secret, req.headers['opscommand-signature'], rawBody); // null when good

Any other answer than 2xx (or no answer) is retried after 1, 2, 4 … minutes (at most 6 hours apart), eight times in all; then the delivery is given up and shown as such beside the endpoint.

The signing secret

Shown once, when the endpoint is added. Rotate it beside the endpoint: the new secret is shown once, and the previous one stays valid for 24 hours (both signatures are sent), so you can update your receiver without missing a delivery; then only the new one signs. The secret is kept sealed in OpsCommand (envelope encryption) and is never shown again.

Slack and Microsoft Teams

Add the channel's incoming-webhook address (Slack: an Incoming Webhooks app; Teams: a Workflows "post to a channel when a webhook request is received", or an incoming-webhook connector). The address is a secret: it is kept sealed and never shown again. Messages say in one line what happened, with a button to open it in OpsCommand — for a page, Acknowledge, which opens the page on the phone. Acknowledging inside Slack or Teams themselves (an installed app with interactive buttons) is a later step; see the owner's actions in STAGE4.md.