Skip to main content

Overview

Kraken Pay will notify your system via webhook when the payment status changes. You’ll receive POST notifications for the following statuses:
The payload is encoded and signed using JWT with the ES256 algorithm (ECDSA using P-256 and SHA-256) and the specified kid. The kid is used to verify the signature by looking up the correct public key in the JWKS available at https://www.kraken.com/.well-known/pay-callback-keys.json.
A given kid will always point to the same key, so you can cache it forever. You will only need to fetch the remote JWKS and update your local set if the JWT is signed with a new kid.
JWT expiration is set to 24 hours. If you have to process the message past the expiry you can simply ignore it.

Claims

JWT claims have the following schema: Because new fields could be added to the payload in the future, your deserialization implementation should handle unknown fields. Example: Decoded JWT claims

Webhook response

On successful validation of the payload your endpoint must return a 200 code with the following JSON payload:
Anything else will be treated as an error.

Examples

Decode and validate JWT

The following are Rust and PHP examples of how to decode the JWT and validate its signature.