Skip to main content
Making a change

Webhook authentication for Loop sources

Turn on HMAC webhook authentication for a Loop source using the webhook secret from Loop Admin, and enforce it safely.

When to use this

Use this guide to turn on webhook authentication for a source that receives webhooks from Loop. Loop signs every webhook it sends with an HMAC signature, so HC can check that each request really came from your Loop account and was not changed on the way.

For how webhook authentication works in general, see Securing a webhook-triggered stream.

Before you start

  • Get the webhook secret from Loop: in Loop Admin, go to the Developer Tools page.

  • Do not use the Loop key in the Control Panel. That key holds the API key HC uses to call Loop, not the webhook secret, so This Source's Key will not work for Loop.

Steps

Set it up in audit mode

  1. Open the stream and, under Source, click Edit.

  2. Scroll to Webhook authentication and enter these settings:

    Setting

    Value

    Auth mode

    HMAC (the sender signs the body)

    Signing Secret from

    Type it in

    Signature header

    X-Loop-Signature

    Algorithm

    sha256

    Encoding

    base64

    Signature prefix

    Leave empty

    Signing Secret

    The webhook secret from Loop Admin > Developer Tools

  3. Leave Enforce unticked and click Update Source.

Enforce once every request passes

  1. Wait for real webhooks to arrive. Returns traffic can be light, so wait until you have seen several.

  2. Edit the source again and tick Enforce. Before it saves, the form shows the Auth Results for the last 7 days for each stream using the source, split into Pass, Fail and Missing.

  3. Confirm only if every request shows Pass. Any Fail or Missing would have been rejected; fix the cause first (see below).

What you should see

In audit mode, webhooks keep arriving as before and each one gets an Auth Result. Once enforced, requests that fail the check are turned away. Rejected requests are lost: they create no event or job and HC cannot retry them.

Keeping it working

  • Secrets are write-only. Once saved, the Signing Secret is never shown again, and leaving the field empty on a later edit keeps the stored value. Keep your own copy in your password manager.

  • To rotate the secret without failed requests, enter the new secret as the Secondary Signing Secret (both are then accepted) and switch Loop to it. Once the Auth Results show requests passing, move the new secret into Signing Secret and clear the secondary.

  • Changes saved while Enforce is ticked take effect immediately. To change a setting on an enforced source, untick Enforce, save the change, check the results, then enforce again.

If it did not work

Every request shows Fail. Check that you used the webhook secret from Developer Tools, not the Loop API key, and that the algorithm, encoding and prefix match the table above.

Every request shows Missing. The Signature header does not match. It must be X-Loop-Signature.

Requests passed, then suddenly fail. The secret changed in Loop. Untick Enforce if it is on, update the secret, and check the results before enforcing again.

An enforced source has stopped receiving data. Untick Enforce first to stop further losses, then investigate. Ask Loop to resend anything rejected in the meantime, if it can.

Was this helpful?

Still need help? Ask the team