Verify a KeySigner audit webhook

Send an audit event to your receiver, check its signature and confirm delivery after a retry.

  1. Set up a test stream

    Use a test organization with webhook streaming enabled and an account that can manage integrations. In the KeySigner console, open Audit, enter your receiver’s HTTPS URL under Webhook stream and select Set stream. Save the secret in your receiver’s secret store. The console shows it once.

    Change a test member’s role after saving the stream. KeySigner sends new events after the stream is saved. Saving a replacement creates a new secret and starts delivery from that point. Export earlier events from Audit.

  2. Verify the webhook signature

    KeySigner sends a JSON POST with up to 100 events in ascending sequence order. sig-delivery-id is the first event’s audit_id. sig-signature contains a Unix timestamp and an HMAC-SHA256 digest in the form t=<seconds>,v1=<hex digest>.

    Pass the original request bytes as a Node.js Buffer, the sig-signature header and the stream secret to this function before parsing JSON. Use the secret exactly as shown in the console. The example allows five minutes of clock skew.

    import { createHmac, timingSafeEqual } from "node:crypto";
    
    export function verifyAuditWebhook(
      rawBody,
      signature,
      secret,
      now = Math.floor(Date.now() / 1000),
    ) {
      if (typeof signature !== "string" || !secret) return false;
      const match = /^t=([0-9]{1,15}),v1=([a-f0-9]{64})$/.exec(signature);
      if (!match) return false;
    
      const [, timestamp, digest] = match;
      if (Math.abs(now - Number(timestamp)) > 300) return false;
    
      const expected = createHmac("sha256", secret)
        .update(timestamp + ".")
        .update(rawBody)
        .digest();
      return timingSafeEqual(expected, Buffer.from(digest, "hex"));
    }

    Example member role change

    This test delivery is shown with an example event ID and time. created_at is the event’s Unix time in seconds. operation_id is null for this role change. For an approval, use it to match the request to its audit records.

    {
      "events": [
        {
          "sequence": 2,
          "audit_id": "7a163628-7cc7-47f4-9f90-9a6f8018f335",
          "event_type": "membership.updated",
          "operation_id": null,
          "created_at": 1794916800,
          "payload": {
            "actor_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
            "principal_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
            "roles": [
              "signer"
            ],
            "status": "active",
            "revision": 2
          }
        }
      ]
    }

    Download example JSON

  3. Test a retry and confirm delivery

    Store verified events using a unique key on the organization and each event’s audit_id. Return a 2xx status once the batch has been stored, including any events already saved. A retry can include additional events, so check every event ID.

    In your test receiver, save the event and return 503 for the first delivery. On the retry, confirm the signature and event ID, then return 204. By default, KeySigner waits 10 seconds before retrying and doubles the delay after each failure, up to one hour. A request times out after 10 seconds.

    First delivery · HTTP 503
    Last failure shows HTTP 503 and the event is still Waiting.
    Retry · HTTP 204
    Your receiver has one stored copy. Last delivered shows the event’s sequence and Waiting drops. Last failure keeps the most recent failure for reference.

Choose a receiver

Send a KeySigner stream directly to an HTTPS endpoint that accepts signed JSON with an events array. To post to a chat channel, point KeySigner at a relay you control. Chat webhooks expect a message in the format shown below.

  1. Receive the event. The relay checks the KeySigner signature before parsing the request and saves or queues each event once by audit_id before returning success.
  2. Choose what to forward. Pick the event types your channel needs. For a package digest mismatch, send a short alert and the request ID. Keep the raw event in your approved audit store.
  3. Check the destination. Store the chat webhook URL as a secret in the relay. Send a sample to a test channel, confirm what appears there, and track downstream delivery failures in the relay.
DestinationJSON the endpoint expects
Audit receiverSigned JSON with an events array. Verify the original request.
Slack{"text": "Package digest mismatch. Request c806c81b-3b8b-4791-9298-f817e46ae00f"}

Slack incoming webhooks

Discord{"content": "Package digest mismatch. Request c806c81b-3b8b-4791-9298-f817e46ae00f", "allowed_mentions": {"parse": []}}

Discord webhook message fields

Google Chat{"text": "Package digest mismatch. Request c806c81b-3b8b-4791-9298-f817e46ae00f"}

Google Chat incoming webhooks

Mattermost{"text": "Package digest mismatch. Request c806c81b-3b8b-4791-9298-f817e46ae00f"}

Mattermost incoming webhooks