XERO Webhook Signature Validation in MuleSoft

Published in

Cloudwerx

4 min readApr 5, 2023

XERO is a cloud-based accounting software platform that allows businesses to manage their finances in real-time. XERO provides webhook functionality to notify subscribed endpoints about various events in the XERO platform. In this blog post, we will explore how to perform XERO webhook signature validation in MuleSoft.

What is Webhook?

A webhook is a way for web applications to provide real-time notifications or data to other web applications or services. It allows one application to automatically send data or trigger events to another application when a specific action or event occurs.

In simple terms, a webhook is a way for two applications to communicate with each other in a real-time or near real-time manner. When an event occurs in one application, it sends a message (payload) to a specified URL (endpoint) in another application. The receiving application can then process the message and take appropriate actions based on its contents.

Webhooks are commonly used for a variety of purposes, such as sending notifications, updating data, triggering workflows or business processes, and integrating different systems. Many web-based services and platforms offer webhook functionality as part of their APIs, making it easy for developers to build integrations and automate workflows between different systems.

What is XERO Webhook Signature Validation?

XERO webhook signature validation is a security mechanism that ensures that webhook requests are coming from a trusted source. The signature is generated using the HMAC-SHA256 algorithm, which involves signing the request with a secret key that is known only to the consumer and the provider.

To perform XERO webhook signature validation in MuleSoft, we need to follow these steps.

Step 1: Implement the Mule application which will be called by the Xero webhook

The first step is to retrieve the webhook payload and signature from the XERO request. The payload is the JSON object that contains the details of the event, and the signature is the HMAC-SHA256 hash of the payload using the secret key.

To retrieve the payload and signature, we can use the MuleSoft HTTP listener to receive the XERO webhook request. We can then extract the payload and signature from the request headers and body.

In this step, we will implement a simple flow that will validate the signature and will return a respective response.

Webhook always sends the JSON response to the mule endpoint, but we need to convert that JSON payload into a raw payload.

Now we are at the actual steps where we are hashing and encoding the payload by using HmacSHA256 and base64 respectively.

We will get the webhook key while configuring the webhook in Xero. Follow this document for creating a webhook.

Xero webhook also sends encrypted and encoded signatures in the header. So we will compare the output from the previous step with the signature which we will get in a header. If we get the output of this comparison as equal to true, that means the request is coming from a trusted source.
At the end of the flow, we will set the HTTP status to 200 and empty the response body for success scenarios. In case the signature does not validate and returns false, for this scenario we will set HTTP status 401 with an empty response.
After deploying the Mule application on Cloudhub, we will get the Cloudhub URL which we will use for webhook validation.

Step 2: Test the Webhook connection from Xero

Let's go to the webhook configuration from the app where we have added our Mule endpoint and used the webhook key in step 1.

Click on the ‘Send Intent to receive’ option which will be located at the end of the configuration. Afterward, Xero will send the below request to our Mule endpoint to validate a signature, once the signature is successfully validated you will have an “OK” status on the webhook UI.

Important

When we try to send “Intent to receive” the very first time, Xero will respond with 3 incorrect HTTP 401 and one correct HTTP 200.
It’s better to have two processes(flows), one is to validate the signature and the second is to fetch the payload after signature validation. To achieve this scenario we can use a VM queue or any other pub-sub model. The first process will validate the signature and send it to the VM queue. And the next process will consume the payload from the queue.

Conclusion

In this blog post, we have explored how to perform XERO webhook signature validation in MuleSoft. By validating the webhook signature, we can ensure that the request is coming from a trusted source and prevent unauthorized access to our systems. With MuleSoft’s powerful integration capabilities, we can easily process the XERO webhook events and integrate them with our business processes.

You can check out the example implementation in the GIT repo.

References

Happy Learning!

Special Note: If you found our information valuable and would like to hear more about how Cloudwerx can help take your business to the next level, we’d love to hear from you. Get in touch with us at www.cloudwerx.co or hello@cloudwerx.co.