Integrations

Webhooks

A webhook endpoint lets Meshanics notify your systems when something happens in the platform: a rollout is created, a device enrolls, an artifact is published, a vulnerability is detected. Each delivery is a signed JSON document describing the event — metadata only, never artifact or payload bytes — POSTed to a URL you configure.

The delivery envelope

Every delivery shares one stable, versioned envelope. Receivers verify the signature over the exact bytes, so the field set is fixed:

{
  "specversion": "1.0",
  "type": "rollout.created",
  "occurred_at": "2026-06-16T09:30:00Z",
  "subject": "…",
  "actor": "user:alice",
  "sequence": 4821,
  "idempotency_key": "4821-…",
  "data": { }
}

data holds the event's own metadata. The sequence and idempotency_key fields let you de-duplicate: the same logical event always carries the same key, so a retry is safe to ignore if you have already processed it.

Verifying signatures

Each request carries an X-Meshanics-Signature header of the form t=<unix-timestamp>,v1=<hex>. The signature is an HMAC-SHA256 over "<timestamp>.<body>" using the per-endpoint signing secret. To verify:

Read the timestamp and signature from the header.
Reject the request if the timestamp is outside your freshness window — this stops replay of an old, validly-signed body.
Recompute the HMAC over "<timestamp>.<rawbody>" and compare in constant time.

The signing secret is generated by the platform when you create the endpoint and shown once, like an API key. It is sealed at rest and never returned again; copy it into your receiver at creation time. Companion headers — X-Meshanics-Event, X-Meshanics-Delivery, and X-Meshanics-Spec — name the event type, the idempotency key, and the envelope version.

Choosing events

An endpoint can subscribe to everything, or filter by event family — rollouts, devices, artifacts, registries, vulnerabilities, and more. A filter matches by exact type or by a trailing wildcard (for example, a rollout. family prefix), and an empty filter means all events.

Delivery, retries, and SSRF protection

The platform tracks the audit log from your subscription point forward, so a new endpoint receives future events rather than the entire backlog. A failed delivery (any non-2xx response or transport error) is retried with exponential backoff up to a bounded number of attempts, then marked failed; you can review per-endpoint delivery history including status, attempt count, and last error.

Because a webhook POSTs to an operator-supplied URL, deliveries are guarded against server-side request forgery: internal, link-local, and cloud-metadata addresses are refused, with private ranges allowable only by explicit per-endpoint opt-in for a deliberate on-prem or same-host receiver.

Testing an endpoint