Authentication

There are three main areas of programmatic interaction with the Hookdeck platform that make use of authentication:

  • Sources
  • Destinations
  • Hookdeck API

The following sections cover the authentication mechanisms and methods that Hookdeck supports for these interactions.

Source authentication

Requests from sources, or inbound requests to the Hookdeck URL defined in a source, can be authenticated in the following ways:

  • HTTP and webhook signature verification: with inbuilt support for a number of third-party providers along with generic signing methods
  • Basic auth: username and password
  • API Key: provided in a configurable HTTP header or query parameter

Additionally, Hookdeck has built-in support for the following providers:

For more information on configuring source authentication, see source authentication.

Webhook handshaking and validation

Some API providers require a validation step, known as a "handshake" or "challenge." While this is not standard across all providers, we do our best to implement validation for any platform that our users integrate with.

Hookdeck provides built-in support for the following platforms and methods:

  • Adobe Acrobat Sign
  • Adyen
  • Asana
  • Facebook
  • Finicity (Mastercard)
  • Google Business Messages
  • helloflex.com
  • HelloSign
  • InFakt
  • Infusionsoft
  • Mailchimp
  • Microsoft SharePoint
  • monday.com
  • Nylas
  • Okta
  • OnFleet
  • Oura
  • PayPal
  • Slack
  • Smartsheet
  • Strava (use STRAVA as verify_token)
  • Trello
  • Twitch
  • Twitter / X (must use our Twitter source verification)
  • Zoom (must use our Zoom source verification)
  • Wallester
  • WebSub generic integration
  • REST Hooks implementation

If your provider requires a handshake and is missing from this list, contact us and we will add support within 24 hours.

For details on how to configure handshaking and verification, see sources.

HTTP and webhook signature verification

Verifying the original provider's signature before processing events prevents bad actors from taking illegitimate actions on your server.

Hookdeck verifies the provider's signature when verification is enabled for your source. In this case, an x-hookdeck-verified header is set to true to confirm the original request was verified, meaning it is safe to verify just the Hookdeck signature.

It's possible to configure verification with most platforms using our dedicated third-party platform, or our "configure-your-own" provider that supports generic implementations of Basic Auth, API Keys, and HMAC signature.

You can also roll your own private verification for any platform that supports Basic Auth, API Key authentictaion or verification using HMAC.

How verification works

When a source has verification configured, Hookdeck will verify every incoming request either with HMAC, Basic Auth, or an API key. Requests that do not match the verification are rejected and labeled "Verification Failed" in the request page.

When using Hookdeck's built in support for third-party providers, it's safe to skip the original provider's verification step and only verify Hookdeck's header. This saves you time, since you only need to implement a single verification process across multiple providers.

Hookdeck will return a HTTP 401 for the HMAC (expect MD5), API Key, and Basic Auth verification methods and for the Shopify, Zoom, Xero, Twitter. For the other providers, Hookdeck will return a HTTP 200.

Destination authentication

Requests to destinations, or outbound requests made by Hookdeck to the URL defined in a destination, can be authenticated as follows:

  • Hookdeck signature: following the Hookdeck signing process using the Hookdeck project signing secret to verify the request
  • Custom SHA-256 signature: with a signing secret provided in a configurable HTTP header to verify the request
  • Basic auth: username and password
  • API key: provided in a configurable HTTP header or query parameter
  • Bearer token: using the standard HTTP Authorization header prefixed with Bearer

For more information on configuring destination authentication, see destination authentication.

Hookdeck webhook signature verification

By default, events sent by Hookdeck to a destination are verified by calculating a digital signature. This authentication method is known as the "Hookdeck Signature".

Each event request includes a x-hookdeck-signature header, generated using the project's secret along with the data sent in the request. To verify the request, compute the HMAC digest according to the following algorithm and compare it to the value in the x-hookdeck-signature and x-hookdeck-signature-2 headers. If they match, the event request was sent from Hookdeck.

If the previous secret was rolled with a delay and is still active, a x-hookdeck-signature-2 header is also provided.

To retrieve the signing secret, head over to the Project Secrets page.

Example of Hookdeck webhook signature verification

Hookdeck signatures use a SHA-256 algorithm and are base64 encoded.

app.use(
  express.json({
    // Store the rawBody buffer on the request
    verify: (req, res, buf) => {
      req.rawBody = buf;
    },
  }),
);

app.post("/webhook", async (req, res) => {
  //Extract x-hookdeck-signature and x-hookdeck-signature-2 headers from the request
  const hmacHeader = req.get("x-hookdeck-signature");
  const hmacHeader2 = req.get("x-hookdeck-signature-2");

  //Create a hash based on the parsed body
  const hash = crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("base64");

  // Compare the created hash with the value of the x-hookdeck-signature and x-hookdeck-signature-2 headers
  if (hash === hmacHeader || hash === hmacHeader2) {
    console.log("Webhook is originating from Hookdeck");
    res.sendStatus(200);
  } else {
    console.log("Signature is invalid, rejected");
    res.sendStatus(403);
  }
});

Hookdeck API authentication

The Hookdeck API supports authentication using a Bearer Token Authentication or Basic Authentication.

For more information, see the authentication section in the API reference.