# Webhooks and integrations

Push governance events to your own tools, and act on Azoth from Slack or Microsoft Teams.

## Governance webhooks

Add an HTTPS endpoint — a GRC or ITSM tool, a SIEM — in **Settings › Integrations and alerts › Webhooks**, then tick the events it receives:

- `decision.blocked` — A decision was sealed with a blocking outcome
- `derogation` — A policy exception, a red-team waiver or a reading of the law was asked, granted, denied or revoked
- `proof.broken` — The hourly verification found the workspace’s chain broken

> Ids, codes and hashes only: no content, no name, no free text. A receiver that needs more asks the API with its own key (`GET /api/v1/journal`).

```
{
  "id": "<delivery uuid>",
  "event": "decision.blocked",
  "workspace_id": "<workspace>",
  "created_at": "<iso date>",
  "data": { "seq": 1042, "entryHash": "<sha256>", "decision": "blocked_by_policy", "traceId": "…" }
}
```

## Checking the signature

Each delivery carries `X-Azoth-Event`, `X-Azoth-Delivery` — stable across retries, deduplicate on it — `X-Azoth-Timestamp` and `X-Azoth-Signature: t=<timestamp>,v1=<hex>`, an HMAC-SHA256 with the endpoint’s signing secret over `<timestamp>.<raw body>`.

```
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyAzothWebhook(rawBody, header, secret, toleranceSecs = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.floor(Date.now() / 1000) - t > toleranceSecs) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(parts.v1, 'hex'), b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

// In a route handler: read the RAW body before parsing it.
export async function POST(req) {
  const body = await req.text();
  if (!verifyAzothWebhook(body, req.headers.get('x-azoth-signature') ?? '', process.env.AZOTH_WEBHOOK_SECRET)) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }
  const event = JSON.parse(body);   // deduplicate on event.id (= X-Azoth-Delivery)
  return Response.json({ ok: true });
}
```

The decision is sealed first. A failed delivery is retried with backoff, five times at most; an endpoint removed before delivery drops its pending events.

## Slack

- Ask Azoth with `/azoth <question>` or a direct message: the same engine as the in-app assistant, with your identity and role. The answer goes only to you, never to a channel.
- Owners and admins linked with MFA receive the approvals and exceptions waiting for them and decide with a click — the role read at the click, four eyes enforced, the decision sealed. A role, a retention change or a red-team waiver always opens in Azoth.
- Link your account with `/azoth link`.

## Microsoft Teams

- Each organisation registers its own single-tenant bot. Its secret is encrypted and checked with Microsoft before it is saved, and Azoth builds its app package.
- Questions in your one-to-one chat with the bot are answered with your identity; approvals and exceptions arrive as cards for owners and admins linked with MFA, decided under the same rules as in Slack.

## PagerDuty and alert channels

Every alert of the workspace — approvals waiting, governance, sign-in anomalies, provider outages, model changes, agent loops stopped, the sealed-decision quota — goes to its alert routes in **Settings › Integrations and alerts › Alerts**: PagerDuty (deduplicated), Slack or Teams channel webhooks, or e-mail, each from the minimum severity it names. Budget thresholds go to the destinations set with each budget.

## GitHub App

- Install the GitHub App from **Settings › Integrations and alerts** and choose its repositories: each pull request on an enabled repository gets a check run. A repository linked to a regression suite gets the result of each case; suites are created with the API (`POST /api/v1/regression/suites`) and no screen links one yet — to test pull requests today, run a suite in your CI with the [CLI](https://www.azothos.ai/docs/cli#ci).
- The same App reads a repository’s AI footprint once you turn the reading on for that repository ([enrichments](https://www.azothos.ai/docs/enrichments#footprint)).
