Webhook Security

Cryptographic Signatures

Bynn implements enterprise-grade webhook security through multiple cryptographic signature mechanisms that ensure webhook authenticity and prevent tampering during transmission. The primary security mechanism utilizes RS256 JWT (JSON Web Token) signatures generated with RSA private keys, providing cryptographically strong authentication that enables webhook recipients to verify both the source and integrity of each webhook delivery.

The JWT signature process includes comprehensive payload signing that covers all webhook data including event metadata, verification results, and customer information. Each webhook delivery includes a complete JWT token in the request headers that contains the signed payload data, enabling recipients to validate the entire webhook content against the signature and detect any tampering or unauthorized modifications.

Organizations receive RSA public keys through secure channels during webhook configuration, enabling local signature verification without requiring external API calls or network dependencies. This approach ensures that webhook signature validation remains fast and reliable even during network issues or high-volume processing scenarios.

📘

JWT Verification

Webhooks will receive POST requests with JSON payloads. Ensure your endpoint is configured to handle these requests and send appropriate responses (HTTP 200/201) to confirm receipt of the webhook.All webhooks from Bynn are signed using RS256 (JSON Web Tokens with a 256-bit RSA key). Verify the authenticity of each webhook using our public key. Webhooks with an invalid signature should be ignored and not trusted. Read more about JWT here

-----BEGIN PUBLIC KEY----- 
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgs4sO1z5s1ZAcrBJJXmB 
fZV69hSvXOLdYhLX7U7oYTV20KCW3xXM37m0bsh48Uq3JqrWVVnqNqNQI8U4ka4v 
4CR80OSWp2oAF/9ORigz/VCsddZ9X6UCkwl7qkhpW1yRBeuMeGWu7d6C43eOo+k/ 
GqjDIrj3GI9DXRcVV/+68sBQVYFz8ybSEbkNsMJNoyz+oNU5zJyqB/Yq0A8D5Od8 
4M2nFD2pHEFF93tEmBR7VaPpK4+87NQ9u5cDEB49hkxm2F54scRNHwcHWQk/MUy1 
RZz0jkprASaj5HfcMXrr/KGdIIRxpJo7Ft4/tN+5YkAWX8Pg13++82uLUz0SsK/E 
BQIDAQAB 
-----END PUBLIC KEY-----

Additional Security Headers

Webhook deliveries include multiple security headers designed to support comprehensive authentication and prevent replay attacks. The X-Webhook-Token header contains a unique identifier for each webhook endpoint, enabling organizations to implement endpoint-specific processing logic and access controls. The Idempotency-Key header provides a unique identifier for each webhook delivery, preventing duplicate processing in scenarios where network issues might cause multiple delivery attempts.

The X-Test-Mode header clearly identifies sandbox webhook deliveries, ensuring that organizations can implement appropriate test data handling and prevent test webhooks from triggering production business processes. The User-Agent header identifies Bynn webhook deliveries with version information, supporting webhook source validation and compatibility management.

All security headers are included in the cryptographic signature calculation, ensuring that header tampering attempts are detected during signature verification and preventing malicious modification of webhook metadata or routing information.