Verify a KeySigner audit webhook
Send an audit event to your receiver, check its signature and confirm delivery after a retry.
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.
Verify the webhook signature
KeySigner sends a JSON
POSTwith up to 100 events in ascending sequence order.sig-delivery-idis the first event’saudit_id.sig-signaturecontains a Unix timestamp and an HMAC-SHA256 digest in the formt=<seconds>,v1=<hex digest>.Pass the original request bytes as a Node.js
Buffer, thesig-signatureheader 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_atis the event’s Unix time in seconds.operation_idisnullfor 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 } } ] }Test a retry and confirm delivery
Store verified events using a unique key on the organization and each event’s
audit_id. Return a2xxstatus 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
503for the first delivery. On the retry, confirm the signature and event ID, then return204. 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.
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.
- Receive the event. The relay checks the KeySigner signature before parsing the request and saves or queues each event once by
audit_idbefore returning success. - 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.
- 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.
| Destination | JSON the endpoint expects |
|---|---|
| Audit receiver | Signed JSON with an events array. Verify the original request. |
| Slack | {"text": "Package digest mismatch. Request c806c81b-3b8b-4791-9298-f817e46ae00f"} |
| Discord | {"content": "Package digest mismatch. Request c806c81b-3b8b-4791-9298-f817e46ae00f", "allowed_mentions": {"parse": []}} |
| Google Chat | {"text": "Package digest mismatch. Request c806c81b-3b8b-4791-9298-f817e46ae00f"} |
| Mattermost | {"text": "Package digest mismatch. Request c806c81b-3b8b-4791-9298-f817e46ae00f"} |