Secrets
Store and replace the signing secret associated with each webhook endpoint.
Each webhook endpoint has its own signing secret. It is separate from an API key and cannot authenticate merchant API calls.
Receive and store a secret#
Registration in Developers → Webhooks & deliveries returns the secret once, in the dialog that confirms the endpoint. Ordinary endpoint lists do not reveal it, and there is no “show secret” operation. Copy it into the receiving server's secret manager before closing the dialog.
The secret is a 43-character base64url-looking string generated for the endpoint. For HMAC, use the UTF-8 bytes of that exact string. Do not base64-decode it or prepend whsec_. See signature verification.
Use distinct secrets for distinct endpoints and environments. Do not place a secret in an endpoint URL, log, exception, or webhook response body.
Lost or exposed secrets#
There is currently no secret-rotation operation or configurable grace period. Replace the endpoint registration and configure the receiver with the new secret.
Deactivate the endpoint first, then register it again. A deactivated endpoint no longer holds its URL, so the replacement may reuse the same URL and receives a new secret; only one active endpoint per URL is allowed in an environment. Verify the new endpoint with a test delivery before relying on it.
For a suspected leak, stop trusting the exposed secret and remove the compromised endpoint registration. Review already received events using their IDs and resource GET responses. Replacing a secret does not undo an action that your application already accepted.
Multiple secrets and signatures#
During a controlled receiver transition, verify the signature against the known secret for the receiving endpoint. The signature header can contain multiple v1 candidates; accept a valid candidate using the verification procedure. The platform does not currently provide automatic dual-signature rotation.
If two endpoint registrations overlap, they can both receive the same event with different delivery IDs. Share the event-ID deduplication store so an overlapping delivery cannot repeat a payment action.