Subscribe to webhook notifications in the Circle developer console and note the X-Circle-Key-Id header sent with each notification.
Retrieve the signing public key by calling GET /v2/notifications/publicKey/{keyId}, substituting the value from the X-Circle-Key-Id header as the path parameter.
Cache the returned base64-encoded public key against its keyId; the key is static per keyId so one fetch suffices until the key rotates.
On each incoming webhook, verify the X-Circle-Signature header against the raw request body using ECDSA-SHA256 with the cached public key.
Reject any request whose signature does not verify or whose X-Circle-Key-Id is absent.
Known gotchas
The signing algorithm is ECDSA-SHA256, not HMAC; using an HMAC library against this endpoint will always fail.
The public key endpoint is /v2/notifications/publicKey/{keyId} — a /v1/ path or a query-parameter form does not exist in the current API.
Always read the key ID from the X-Circle-Key-Id request header; do not hard-code a key ID.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp