Authentication and Security

jetpay's webhook system implements two layers of authentication to ensure security at both the api level and the webhook delivery level api authentication all webhook management operations (register, list, update, delete) require authentication using your company api token include your token in the authorization header of api requests webhook request authentication every webhook delivery includes a jwt (json web token) in the authorization header with the format authorization bearer \<jwt> this jwt is signed using the rs256 algorithm (rsa signature with sha 256) and must be verified by your webhook endpoint to ensure the request genuinely comes from jetpay jwt structure the jwt contains two main parts headers and claims headers alg algorithm used for signing (always "rs256") kid key identifier for retrieving the correct public key from jwks endpoint claims jti unique token identifier (uuid) iat issued at timestamp (unix epoch) exp expiration timestamp (unix epoch, typically 90 seconds from issuance) iss issuer (always "jetpay") sub subject (always "webhook") payload hash base64url encoded sha 256 hash of the request body jwks endpoint for public key retrieval to verify jwt signatures, retrieve jetpay's public keys from our jwks (json web key set) endpoint endpoint get / well known/jwks json this endpoint returns a standard jwks response containing the public keys needed for jwt verification payload hash verification the payload hash claim provides additional integrity verification compute the sha 256 hash of the raw request body base64url encode the hash compare with the payload hash claim in the jwt this ensures the request body hasn't been tampered with during transit jwt expiration jwt tokens have a configurable expiration time, defaulting to approximately 90 seconds from issuance verify the exp claim to ensure the token hasn't expired expired tokens should be rejected security best practices always verify jwt signatures never trust webhook requests without validating the jwt signature using the public key from our jwks endpoint check token expiration reject requests with expired jwts verify payload hash compute and compare the payload hash to prevent tampering use https only configure webhook endpoints with https to protect data in transit validate event ids track received event ids to detect and handle duplicates secure token storage if using callback api key , store it securely (we'll include it in requests to your endpoint) implement rate limiting protect your endpoint from potential abuse monitor failed deliveries set up alerts for webhooks entering backing off or failed states