Bizappay

Overview

This node interacts with the Bizappay API, specifically focusing on webhook-related operations in this context. The Verify Signature operation allows users to validate the authenticity of incoming webhook requests from Bizappay by verifying their HMAC-SHA256 signature using a shared secret key.

This verification is crucial for security, ensuring that webhook payloads have not been tampered with and genuinely originate from Bizappay. Typical use cases include:

• Confirming payment notifications or status updates received via webhooks.
• Preventing fraudulent or spoofed webhook calls from unauthorized sources.
• Automating workflows triggered by verified webhook events, such as updating order statuses or sending notifications.

For example, when a payment is completed, Bizappay sends a webhook with payment details and a signature header. This node verifies the signature before processing the payment data further.

Properties

Output

The output JSON object includes:

• valid (boolean): Indicates whether the webhook signature is valid (true) or invalid (false).
• message (string): A human-readable message stating the verification result.
• signature_info (object):
  • received_signature: Partial display (first 8 characters) of the signature received in the webhook header.
  • expected_signature: Partial display (first 8 characters) of the computed expected signature based on the payload and secret.
  • algorithm: The cryptographic algorithm used, which is "HMAC-SHA256".

Additionally, the node adds a _security metadata object summarizing:

• verificationStatus: A checkmark or cross emoji indicating validity.
• recommendation: Guidance on whether it is safe to process the webhook.
• securityLevel: "HIGH" if valid, "CRITICAL_RISK" if invalid.

If an error occurs during verification (e.g., missing inputs or cryptographic errors), the output will contain:

• valid: false
• message: Error description
• error: Error message string
• error_type: "SIGNATURE_VERIFICATION_ERROR"

Dependencies

• Requires Node.js built-in crypto module for HMAC SHA256 hashing.
• No external API calls are made during signature verification; it is a local cryptographic operation.
• Users must provide the webhook secret key securely, typically stored in n8n credentials or environment variables.
• Input webhook payload must be provided as a JSON string exactly as received.
• The signature header must be extracted from the incoming webhook HTTP headers.

Troubleshooting

• Common Issues:

  • Missing or empty webhook payload, signature, or secret parameters will cause the node to throw an error.
  • Incorrect webhook secret key will result in signature mismatch and invalid verification.
  • Altered or malformed webhook payloads will fail verification.
  • Signature header not properly formatted (missing sha256= prefix) may cause incorrect comparison.

• Error Messages:

  • "Webhook payload, signature, and secret are all required": Ensure all three inputs are provided.
  • "Webhook signature is invalid": The signature does not match the expected value; verify the secret key and payload integrity.
  • "Error verifying webhook signature": General cryptographic error; check input formats.
  • "Error parsing webhook payload JSON": If payload is not valid JSON, parsing fails.

• Resolution Tips:

  • Double-check that the webhook payload string matches exactly what was received (no extra whitespace or formatting changes).
  • Confirm the webhook secret key matches the one configured in Bizappay dashboard.
  • Extract the signature header correctly from the incoming HTTP request.
  • Use the node’s output messages and _security metadata for quick validation feedback.

Links and References

• Bizappay Webhook Documentation (hypothetical link for reference)
• Understanding HMAC and Webhook Security
• Node.js Crypto Module Documentation

This summary covers the static analysis of the Bizappay node's webhook signature verification operation, detailing its inputs, outputs, and usage considerations without exposing any internal credential names or implementation specifics beyond the public interface.