Hookdeck Source Verification

Author picture Alexandre Bouchard

Hookdeck Source Verification


Hookdeck Integrations have been renamed to Source Verification and this blog post has been updated accordingly.

We're thrilled to release Source Verification! Source Verifications were built to make it easier to integrate with different providers. To start, Source Verification allows you to:

  • Perform webhook URL challenges like Twitter CRC
  • Validate webhook authenticity by verifying the signature (or other security strategies)

Right now we have Twitter, Stripe, Shopify, Postmark, and GitHub as source out of the box. However, you can easily create as many integrations as you need to cover all your providers by using the HMAC, Basic Auth, or API Key template.

Verification is optional. You still have the choice to verify all of your webhooks on your server.

All secrets provided to Hookdeck as AES encrypted.

Hookdeck Source Verification blog post

Why Source Verification?

When we started Hookdeck, our philosophy was to build a platform that was provider agnostic. In other words, we wanted any webhook to work on Hookdeck.

This is still the case and we remain committed to that, but with Source Verification we have the chance to go a step further and expand the functionality for specific commonly used providers.

Additionally, some providers like Twitter have requirements that can only be solved on a case-by-case basis. Therefore, in the effort to support every provider, Source Verification now gives us a way to add the required functionality from certain providers to make sure we are able to support the API provider you need.

Creating a Source Verification

Source verifications config

Behind the scenes, the Source Verification (even the ones out of the box) re-use the same three templates:

  • HMAC
  • Basic Auth
  • API Key

This technically means that there should be nothing stopping you from creating the integration you need. Unless it's a handshake (contact us, we will implement it!), you have complete control of your webhook security.

integration behind the scenes

See the docs on adding a Source Verification for more details.

How does the Source Verification feature work?

  • You need to configure with an Source Verification that supports verification. Hookdeck will automatically perform the validation to all incoming requests sent to that Source.
  • If the request passes the verification, it will be accepted and sent to the Destination within that connection.
  • In the event that the request doesn't pass the verification, Hookdeck will still return an HTTP 200 code to the sender but the request will be discarded and logged as a failed validation request.

With this change, Hookdeck has added the X-Hookdeck-Verified header in the requests forwarded to your destinations. This gives you a way to validate that the original request was indeed verified by Hookdeck.

Leveraging Source Verification with Hookdeck Signature

Source Verification plays really nicely with Hookdeck's Signature because you can offload the responsibility of webhook security to Hookdeck.

Imagine you were to decide to add Source Verification to all your Sources. You would have the opportunity to implement a unified verification (only to verify Hookdeck's signature) on your servers for all your webhooks, instead of implementing platform-specific logic.

Source Verification with signature verification

The X-Hookdeck-Signature is a SHA-256 hash that can be verified with your signature key. You can read the docs here.

What to look for next

Source Verification is just the beginning of our ambitions to make it easier to integrate with other services. We will be adding more features in the same vein to make it simpler for you to use webhooks from different platforms. We plan on helping with registering and creating webhooks, handling automatic reconciliation via API pooling, and more!

Alex Co-Founder