Webhooks

Webhooks send event notifications to your endpoint when something happens in Guardian. Guardian uses tiny event payloads that describe what happened. You need to use the API to fetch more details if needed.

How webhooks work

Event occurs: A token operation or system event happens in Guardian.
Notification sent: Guardian sends a webhook payload to your configured endpoint.
Process payload: Your endpoint receives a lightweight event description.
Fetch details: Use the API to fetch full details if needed.

Configuration

Register a webhook with its URL, the event types it subscribes to and an optional HMAC key (see Register webhook). Every webhook subscribed to an event type receives its own copy of each event of that type. Webhooks cannot be edited. To change the URL, the events or the HMAC key, register a new webhook and then delete the old one. Deliveries that are already queued, including their retries, still go to the URL of the deleted webhook. Use a publicly reachable HTTPS URL. Guardian does not deliver to private or reserved IP addresses; such deliveries fail and are retried like any other failed delivery.

Payload

Each notification is a POST request with a JSON body:

{
  "id": "9c2e4d1a-7b3f-4e8a-a5d6-1f0b8c3e2a97",
  "created_at": "2026-10-14T09:21:07.482913Z",
  "type": "network.token.deleted",
  "reason": "Network token deleted",
  "related_object": {
    "id": "e4b8c1d2-3a5f-4b6e-9c7d-8f2a1e0b3c4d",
    "url": "https://guardian.example.com/api/network/tokens/e4b8c1d2-3a5f-4b6e-9c7d-8f2a1e0b3c4d"
  }
}

Field	Description
`id`	Unique ID of the event. It stays the same across retries, so use it to detect duplicates.
`created_at`	When the event occurred, in ISO 8601 (UTC).
`type`	The event type, for example `network.token.updated`.
`reason`	A human-readable description of why the event was sent.
`related_object`	The `id` of the affected resource and, where available, the `url` to fetch it from.

See Event notification for the full schema.

Responding to Webhooks

Guardian counts a delivery as successful when your endpoint answers with any 2xx status code, for example 200, 202 or 204, within 15 seconds.

Acknowledge first, process later. Store the event and return 2xx right away, then do the work asynchronously. A slow response counts as failed and the event is sent again.
Keep the response body empty. Guardian ignores the body. If you do return one with content-type: application/json, it must be valid JSON; otherwise the delivery counts as failed.
Every other outcome is a failure. Any status outside 2xx, including 4xx, a timeout, and a connection or TLS error, causes a retry. There is no status code that stops retries.
Register the final URL. Guardian follows redirects, but a 301, 302 or 303 redirect turns the request into a GET without the payload.

Retries

Guardian makes up to six attempts per event and webhook. After a failed attempt, it waits before trying again:

Attempt	Sent
1	When the event occurs
2	15 seconds after attempt 1 failed
3	30 seconds after attempt 2 failed
4	1 minute after attempt 3 failed
5	2 minutes after attempt 4 failed
6	4 minutes after attempt 5 failed

Each wait varies by up to 10% so retries don’t arrive in lockstep. The last attempt happens about eight minutes after the first. If the sixth attempt fails, Guardian drops the event. The webhook stays active for later events, but failed deliveries cannot be listed or sent again. If your endpoint was unavailable for longer, use the API to bring your data up to date, for example List tokens for network tokens.

Duplicates and Ordering

The same event can arrive more than once, for example when your endpoint processed it but answered too late. Retries carry the same id, the same body and the same signature, so store the id of each processed event and skip events you have already seen. Events are not guaranteed to arrive in the order they occurred. Several deliveries run in parallel, and a retried event can arrive after a newer one. Rather than relying on the order, fetch the resource from related_object.url to read its current state; a deleted network token returns 404.

Security

Set an HMAC key when you register the webhook, so you can verify that notifications come from Guardian.
Configure secure (HTTPS) endpoints.
Validate webhook signatures before processing requests.

HMAC signing

When the webhook has an HMAC key, every notification carries an x-hmac-signature header: the HMAC-SHA256 of the raw request body, encoded as lowercase hex. Guardian uses the key exactly as you registered it, as a string; it is not base64-decoded. Without an HMAC key, the header is not sent.

How to verify

Calculate the HMAC using:
- The raw payload you received in the webhook body, before any JSON parsing
- Your HMAC key
- The SHA256 hashing function
Compare the calculated value with the x-hmac-signature header you received, using a constant-time comparison.

If they match, the webhook was sent by Guardian and was not modified in transmission.

Example

For the HMAC key my-webhook-signing-key and this raw body:

{"created_at":"2026-10-14T09:21:07.482913Z","id":"9c2e4d1a-7b3f-4e8a-a5d6-1f0b8c3e2a97","reason":"Network token deleted","related_object":{"id":"e4b8c1d2-3a5f-4b6e-9c7d-8f2a1e0b3c4d","url":"https://guardian.example.com/api/network/tokens/e4b8c1d2-3a5f-4b6e-9c7d-8f2a1e0b3c4d"},"type":"network.token.deleted"}

the x-hmac-signature header is:

39f56bb3d2027cf2364c99f34f4b2ac022825df397445be2b24c17cb1da11a95

Verification in Node.js:

const crypto = require('crypto');

function isValidSignature(rawBody, signature, hmacKey) {
  const expected = crypto.createHmac('sha256', hmacKey).update(rawBody).digest('hex');
  const received = String(signature ?? '');
  return received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Pass the body exactly as received, for example as a Buffer from a raw body parser. Re-serializing parsed JSON can change the bytes and break the signature.

Getting Started

Features

Management

Migrations

How webhooks work

Configuration

Payload

Responding to Webhooks

Retries

Duplicates and Ordering

Security

HMAC signing

How to verify

Example

​How webhooks work

​Configuration

​Payload

​Responding to Webhooks

​Retries

​Duplicates and Ordering

​Security

​HMAC signing

​How to verify

​Example

How webhooks work

Configuration

Payload

Responding to Webhooks

Retries

Duplicates and Ordering

Security

HMAC signing

How to verify

Example