Create and rotate webhooks

Webhooks are the outbound integration surface — Slack, PagerDuty, SIEM collectors, anything that accepts an HTTPS POST. NovaVMS signs every delivery with HMAC-SHA256 so the receiver can verify the payload came from you and was not tampered with in transit. The signing secret is the single most sensitive item in a webhook definition: anyone with it can forge deliveries that look authentic. Operators create webhook definitions (URL, events filter, name); admins and owners are the only roles that can view or rotate the secret (D81).

Caution

Rotating a secret invalidates the old one immediately. Every downstream consumer that still signs with the old secret will fail verification until you update its configuration. Plan a rolling cutover (see Common variations) for any integration you cannot afford to break.

Procedure

Create a webhook

1. Open Settings -> Webhooks from the left nav.
2. Click + Create Webhook.

3. Fill in the form:
   • Name — human-readable label, for example Slack SOC channel.
   • URL — must be HTTPS. HTTP is rejected with a validation error.
   • Event types — tick any of alert, event, camera_status, gateway_status.
   • Enabled — leave on unless you want to stage first.
4. Click Create.

5. The secret is shown once in a modal. Copy it into your downstream integration’s secret store now — you cannot retrieve it later.

Signature verification contract: the receiver computes HMAC-SHA256(secret, body) and compares (constant-time) against the hex digest in the X-Webhook-Signature header. Each delivery also carries X-Webhook-ID (unique UUID) and X-Webhook-Timestamp (ISO 8601) for idempotency and replay protection.

Rotate a secret

1. Open Settings -> Webhooks.
2. Click Edit on the webhook.
3. Click Rotate Secret.

4. A new secret appears in a modal. Copy it immediately and update your downstream integration.

The old secret is invalidated on save — not when the modal closes. Anything still posting with the old secret will see signature-verification failures from the next delivery onward.

The audit log records webhook.secret_rotated with the actor user_id and a timestamp.

Common variations

• Rolling rotation (no downtime). Create a second webhook with the same URL but the new secret. Update the receiver to accept either secret during a migration window. Verify new deliveries signed with the new secret arrive. Delete the old webhook. This pattern avoids any window where deliveries are rejected.
• Test a delivery without waiting for a real event. Click Test on the webhook row. NovaVMS sends a canned payload with test: true using the current secret. The delivery appears in the delivery history.
• Auto-disable after failure. After 5 consecutive 5xx responses, NovaVMS sets the webhook enabled=false. The UI badge shows [ERR]. Fix the downstream issue, then flip the toggle back on.

If this didn’t work

• URL rejected with validation error — the URL must be HTTPS. HTTP endpoints, localhost without TLS, and self-signed certs without a valid CA chain all fail.
• Create returns 409 “Max webhooks reached” — you are at 20 webhooks per org. Delete unused ones or consolidate event filters onto fewer webhooks.
• Downstream integration starts returning 401 right after rotation — it is still signing with the old secret. Update its configuration and retry. The delivery history shows signature_invalid as the failure class.
• Rotate button not visible — your role is operator, not admin or owner. Webhook secret rotation is governance (D81). See Roles and permissions.

Related

• Alert rule schema — the payload shape when event_type=alert
• Audit actions — webhook.created, webhook.secret_rotated entries
• Roles and permissions — definition CRUD (operator) vs secret rotation (admin)