How to Verify Webhook Signatures

David Taing


Payment Declined - Webhook Event

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:

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?

How to generate a webhook signature by the Pineapple Pen Guy

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

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

* 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

Written By David Taing

Dave is an ex-Property Manager turned Fullstack TypeScript Engineer. He mostly spends his time gluing APIs together at work, building side-projects, regularly going to tech meetups, and sharing the things he learns online.