Maya Webhook Signature Verification: Environment‑specific key handling

Question

Maya Webhook Signature Verification: Environment‑specific key handling
Goal: Validate that the integration can correctly verify webhook signatures when operating in the Maya sandbox, ensuring that the same code path works in production without hard‑coding keys or changing logic.
Constraints: Maya documentation states that sandbox and production use distinct base URLs and key pairs. It is unclear whether the signature algorithm or key format changes between environments, and whether a separate public key endpoint is exposed for sandbox verification.
Uncertainty: If the sandbox uses a different HMAC secret or RSA public key, the verification routine may need to adapt, potentially breaking the idempotent processing logic that relies on a consistent signature scheme.

Does Maya expose a distinct public key or HMAC secret for sandbox webhook verification?
Are the cryptographic algorithms (e.g., HMAC‑SHA256 vs. RSA‑SHA256) identical across sandbox and production?
Can the sandbox simulate duplicate or replayed webhook deliveries to test idempotency logic?

Tasadduq Burney · Answer

Handling Maya Webhook Secrets Across Environments
Maya uses distinct HMAC secrets for sandbox and production environments. To maintain a consistent code path without hard-coding keys, you must inject the environment-specific secret via environment variables or a configuration provider. The cryptographic algorithm remains identical across both environments, ensuring that your verification logic does not need to change when promoting code to production.

Environment-Specific Key Details
Maya does not use RSA public keys or a JWKS endpoint for webhook verification; it relies on a pre-shared HMAC secret. These secrets are provisioned per merchant account and are entirely separate for each environment:

Sandbox: Generated and retrieved via the Maya Business Manager sandbox portal.
  Production: Generated and retrieved via the live Maya Business Manager portal.

Cryptographic Consistency
The signing algorithm is HMAC-SHA256 for both sandbox and production. The signature is typically computed using the raw request body and the environment-specific secret. Because the algorithm is consistent, your idempotent processing logic—which should rely on the payload's unique event ID rather than the signature itself—will remain stable across environments.

Implementation Steps for Environment Parity

Externalize the Secret: Store the secret in an environment variable (e.g., MAYA_WEBHOOK_SECRET).
  Capture Raw Body: Ensure your middleware captures the raw, unparsed request body, as parsing JSON before verification will invalidate the HMAC hash.
  Verify Signature: Compute the HMAC-SHA256 hash of the raw body using the environment variable and compare it to the signature header (typically X-Signature or Maya-Signature).
  Test Idempotency: Since the Maya sandbox does not provide a native "replay" button for specific webhooks, manually resend the same raw payload and signature via a tool like cURL or Postman to verify that your system ignores duplicate event IDs.

Verification Command
You can verify your sandbox secret manually using OpenSSL to ensure your code's implementation is correct:
echo -n 'RAW_PAYLOAD_BODY' | openssl dgst -sha256 -hmac "YOUR_SANDBOX_SECRET"

Diagnostic Requirement
To provide a more specific implementation example, please confirm the exact header name (e.g., X-Signature vs Maya-Signature) being received in your current sandbox traffic, as this has varied across Maya API versions.

Maya Webhook Signature Verification: Environment‑specific key handling

Maya Webhook Signature Verification: Environment‑specific key handling

1 answer

Handling Maya Webhook Secrets Across Environments

Environment-Specific Key Details

Cryptographic Consistency

Implementation Steps for Environment Parity

Verification Command

Diagnostic Requirement

Your perspective belongs here.

0 question comments