Send audit events and drift to your tools

TL;DR

1. Add a destination

1. Open the organisation in the portal and choose the Integrations tab.
2. Choose the tool, give the destination a name, and choose what it receives: the audit log, the drift results, or both.
3. Fill in the tool's fields from the section below, then save.
4. Press Send test event. Plotwork sends one event of type test at once and says whether the tool took it, or why not, in one sentence such as "Datadog answered HTTP 403."

Each destination then shows, in plain sentences, when it last took a batch, its last error, how many events wait to be sent, how many were given up on, and when it tries next.

2. Datadog

Audit events and drift runs go to the Logs intake, https://http-intake.logs.<site>/api/v2/logs. Drift runs also go to the metrics API, https://api.<site>/api/v2/series.

Each log has ddsource and service set to plotwork, a plotwork_type tag (audit_event, drift_run or test), a one-line summary as its message, and the whole event under the plotwork attribute.

For each diagram a drift run checked, Plotwork sends two gauges tagged repo:<repository> and source:<name>:

A point carries the time it is sent, because Datadog refuses points more than an hour old and a retried batch can be older.

3. Dynatrace

Audit events and drift runs go to Log Monitoring API v2, https://<environment id>.live.dynatrace.com/api/v2/logs/ingest. Drift runs also go to Metrics API v2, /api/v2/metrics/ingest, as line protocol.

Each log record has the event as JSON in content, its time in timestamp, log.source set to plotwork, and the attributes plotwork.type, plotwork.org_id, and plotwork.action or plotwork.repository. The drift metrics are plotwork.drift.stale and plotwork.drift.checked, gauges with the dimensions repo and source, as for Datadog, stamped by Dynatrace when they arrive.

4. Splunk

Events go to the HTTP Event Collector.

Each event has host set to plotwork.dev, source set to plotwork, a sourcetype of plotwork:audit_event, plotwork:drift_run or plotwork:test, its time in seconds, and the whole event as event.

5. Microsoft Sentinel

Events go to a Log Analytics workspace through the Azure Monitor Logs Ingestion API, with a token Plotwork asks Microsoft Entra ID for with the client credentials you give. Plotwork keeps the token in memory until five minutes before it expires, and never stores it.

Set it up in Azure once:

1. In Microsoft Entra ID, register an application and add a client secret. Note the tenant id, the application (client) id and the secret's value.
2. In the workspace that Sentinel uses, create a custom table from a data collection rule (Tables, Create, New custom log (DCR-based)), named for example PlotworkAudit_CL, with the columns below. Azure creates the rule and its stream, Custom-PlotworkAudit_CL.
3. Give the application the Monitoring Metrics Publisher role on the data collection rule.
4. From the rule's JSON view, copy its immutableId. From its data collection endpoint (or the rule's own logs ingestion endpoint), copy the logs ingestion address.

6. A webhook

Plotwork posts each batch to your HTTPS address as a JSON array of events.

Answer with a 2xx status within 10 seconds. Any other status, a redirect, or no answer is a failure, and the batch is sent again later. Check the signature over the body exactly as it arrived, before parsing it, and refuse a timestamp more than five minutes from your clock, so a captured request cannot be replayed. An event can arrive twice, so use its id to skip one you have seen.

In Node:

1import { createHmac, timingSafeEqual } from 'node:crypto'2
3export function verifyPlotworkSignature(secret, header, rawBody, toleranceSeconds = 300) {4  const parts = Object.fromEntries(header.split(',').map((part) => part.trim().split('=', 2)))5  const timestamp = Number(parts.t)6  if (!Number.isInteger(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false7  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')8  const given = String(parts.v1 ?? '')9  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected))10}

In Python:

1import hashlib2import hmac3import time4
5
6def verify_plotwork_signature(secret: str, header: str, raw_body: bytes, tolerance_seconds: int = 300) -> bool:7    parts = dict(part.strip().split("=", 1) for part in header.split(",") if "=" in part)8    try:9        timestamp = int(parts.get("t", ""))10    except ValueError:11        return False12    if abs(time.time() - timestamp) > tolerance_seconds:13        return False14    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()15    return hmac.compare_digest(expected, parts.get("v1", ""))

7. What is sent

Every event has a type, a version (1), an id, the organisation's orgId, and at, an ISO 8601 time in UTC.

Nothing else is sent: never a diagram's source, a file's content, the names of what changed, a key's value or a token.

8. How delivery works

9. The API

The Integrations tab uses these routes. They take the portal's session, the owner's or an admin's, and are not in the OpenAPI reference.

Adding, changing and removing a destination is recorded in the audit log as orgs.integration.create, orgs.integration.update and orgs.integration.delete, without the secret.

See also