Payiano Verify Webhook Payload Signature

Overview

Verifying the webhook signature is an important step in ensuring the authenticity and integrity of the webhook events sent by Payiano to your server. This guide will walk you through the process of validating the signature to confirm that the payload has not been tampered with and that it indeed comes from Payiano.

What is a Webhook Signature?

A webhook signature is a hash generated using a signature secret and the payload of the webhook event. Payiano includes this signature in the X-Payiano-Webhook-Signature header of each webhook request, allowing you to verify the integrity and authenticity of the data received.

Steps to Verify the Webhook Signature

There are two ways to verify the webhook event, you are free to use either ways. Each webhook request sent by Payiano includes a header named X-Payiano-Webhook-Signature. This header contains the HMAC signature.

1
{ 2
 "request_headers": { 3 "Content-Type": "application/json", 4 "X-Payiano-Webhook-Event-Id": "01j3521znn3b6wderr4vbyq18n", 5 "X-Payiano-Webhook-Event-Attempt-Id": "01j354j6nkwh3mdvhs6dsmswt8", 6 "X-Payiano-Webhook-Signature": "b3924d021e7f092c06a03c1309a12fad5e56c78381229c8cabb4a4335e6c1a18" 7 } 8}

1. Manual Method

  • To verify the authenticity of a webhook event, start by computing the HMAC signature on your server using the SHA-256 hashing algorithm. Use the payload of the webhook event as outlined in the build valid signature guide. The signature should be generated using the signature secret associated with your specific webhook URL.
  • Once you have computed the signature, compare it with the value provided in the X-Payiano-Webhook-Signature header included in the webhook request. This comparison ensures that the webhook event is genuine and has not been tampered with. If the signatures match, the event is considered valid.

2. Postback Method

Alternatively, instead of verifying the signature yourself, you can use the postback method by sending the event back to the verify webhook signature REST API endpoint. This allows Payiano to handle the signature verification for you, simplifying the process.

By leveraging the postback method, you can offload the complexity of signature verification to Payiano, ensuring that the data you process is authentic and has not been tampered with. This method provides a streamlined and secure way to validate webhook events, enhancing the reliability and security of your webhook integrations.

When using the postback method, it is essential that the webhook event data be posted back exactly as it was received, without any changes in formatting or content. Any alterations, including parsing the JSON to an array/object and then re-serializing it back to a JSON string, can lead to verification failure. Ensuring the integrity of the original payload is critical for maintaining successful verification.

Testing Your Webhook Signature Verification

Before going live, test your signature verification implementation thoroughly. Use tools like Ngrok to create a secure tunnel to your local machine and simulate webhook events from Payiano to ensure your server correctly verifies the signatures.

Common Issues and Troubleshooting

1. Signature Mismatch

  • Ensure that you are using the correct signature secret associated with the webhook URL.
  • Verify that the payload used to compute the signature matches the exact payload received from Payiano.

2. Incorrect Payload Handling

  • Ensure that any changes in the payload, such as new lines or different encodings, are handled consistently.
  • Ensure your server's clock is synchronized to avoid issues with timestamp validation.