Webhooks v1 are legacy and being phased out. If you have existing integrations
with v1 endpoints, learn how to migrate to
v2.
Signature scheme
Circle signs each v2 webhook notification with theECDSA_SHA_256 algorithm.
Every notification includes two headers your endpoint uses to verify the
signature:
X-Circle-Signature: the digital signature of the notification body, base64-encoded.X-Circle-Key-Id: the UUID of the public key that signed the notification.
Verify a signature
1
Read the signature and key ID from the headers
Extract
X-Circle-Signature and X-Circle-Key-Id from the incoming webhook
request’s headers.2
Fetch the public key
Using the value of A successful response returns the base64-encoded public key:
X-Circle-Key-Id, call your product’s public key endpoint to
retrieve the public key and algorithm. Replace <public_key_endpoint> with the
endpoint for your product:- Wallets,
Contracts,
Gateway,
Circle Mint,
Digital Asset Accounts,
CPN Managed Payments, and End User Onboarding:
/v2/notifications/publicKey/{keyId} - CPN:
/v2/cpn/notifications/publicKey/{keyId} - StableFX:
/v2/stablefx/notifications/publicKey/{id}
3
Verify the signature against the raw body
Use the public key to verify the signature against the raw request body.
Parsing the JSON and re-serializing it changes the byte order, so the signature
no longer matches.If verification succeeds, the notification is authentic. If it fails, reject the
request.