teeang

How to Verify Webhook Signatures

---

What Are Webhooks?

Webhooks are a way to allow you to subscribe to real-time events from other applications. They’re well suited for asynchronous workloads and communicating via North-south traffic. A classic example is taking a payment:

• The payment process is initialized
• And sometime later the amount leaves the payer’s account
• Or the payment gets declined

This process can take a few days to complete and webhooks are a great way for you to get real-time updates when payment events occur.

How Are Webhooks Secured?

As a security measure, the webhook sender will send a signature in the headers. This signature is generated by putting the request body and a secret into a hashing algorithm (as shown by the Pineapple Pen guy above).

Why Should We Verify Webhook Signatures?

1. It allows us to verify who sent the webhook.
2. Determine if the body was tampered by an attacker. A different body results in a different signature.
3. With certain webhook senders and time-based signatures, we can also reject out-of-date webhook events and prevent replay attacks.

So How Do We Verify a Webhook’s Signature? - A Quick Overview

At a high level

• The webhook sender has already pineapple-penned a signature
• We’ll need to do the same on our side and generate a signature
• Then we compare the two

1. Get the signature that was sent by the Webhook’s sender.

The webhook signature can be found in the headers. Details on the specific header name can be found in the docs. Or by inspecting the headers if you are brave.

(Will recommend reading the docs though. Looking at you, Davo.)

2. Recreate the Signature on Our Side

• The hashing algorithm - sometime the header name may indicate the algorithm used (e.g. signature-sha256). Though you’ll probably find the specific header name in the docs.
• The hashing secret - provided by the sender.
• Raw HTTP request body - super-duper important that we use the raw HTTP body when generating the signature. This will require you to disable body-parsing for you webhook endpoints. *

* I don’t fully understand it, but when the body is processed in your language’s or framework’s body parser it may change the binary representation and therefore the resulting signature.

3. Finally, Compare the Two Signatures

If the two signatures match, happy days, and we’re good to go. If not, then there’s something wrong.

Thanks for reading!

PS. Probably need to lay off the memes. LOL

---