Skip to main content
Making a change

Securing a webhook-triggered stream

Make a webhook-triggered stream check that every request really comes from your sender, starting in audit mode before you enforce it.

When to use this

Use this guide to make sure the webhooks reaching a stream really come from the system you expect. It applies to streams whose source is triggered by a webhook (the stream page shows Trigger: Static web hook).

By default, the only check on an incoming webhook is the Auth Token in the webhook URL. Anyone who has the URL can send data that HC will process as genuine, and URLs leak through logs, screenshots and shared configuration. Webhook authentication adds a second check: the sender has to prove who it is on every request.

Before you start

  • Authentication is set on the source, not the stream, so it applies to every stream that uses that source.

  • Check which method your sender supports. The options are HMAC (the sender signs the body), Header Secret and Basic auth. Shopify signs its webhooks with HMAC, which is the example used here.

Steps

  1. Go to Streams and open the stream.

  2. Under Source, click Edit. The Update Source page opens.

  3. Scroll down to Webhook authentication. Auth mode shows None (the Auth Token in the URL only) if nothing is set yet.

  4. Set Auth mode to HMAC (the sender signs the body).

  5. Set Signing Secret from to This Source's Key. For a Shopify source, Signature header, Algorithm and Encoding fill in with Shopify's values (X-Shopify-Hmac-Sha256, sha256, base64), and Signature prefix stays empty.

  6. Leave Enforce unticked for now.

  7. Click Update Source.

What you should see

The message The source was updated! and the stream page. Webhooks keep arriving as before.

Audit first, then enforce

With Enforce unticked, HC checks every request but lets it through, and records an Auth Result for it. This lets you confirm the set-up is right without risking any data.

Once the Auth Results show every request passing, edit the source again, tick Enforce and click Update Source. From then on, requests that fail the check are rejected and lost, so do not tick it until you are sure.

Which Shopify secret to use

This Source's Key works for webhooks that your Shopify app subscribed to: Shopify signs them with the app's secret, which is stored in the key. Webhooks created by hand in Shopify admin (Settings > Notifications > Webhooks) are signed with the store's own key instead. For those, copy the value shown after "Your webhooks will be signed with" on that Shopify page and enter it in HC as the signing secret.

If it did not work

Auth Results show requests failing. Leave Enforce unticked. Check that the signing secret matches how the webhook was created in Shopify (see above), and that the signature header, algorithm and encoding match what the sender uses.

Webhooks stopped arriving after you ticked Enforce. The requests are failing the check and being rejected. Untick Enforce, save, and check the Auth Results before trying again.

Related

Was this helpful?

Still need help? Ask the team