Succeeding with HookdeckUsing the CLIUsing the APICompatibilityCompliance and security

Succeeding with Hookdeck

Hookdeck aims to alleviate the many challenges that come with developing webhook integrations. The following practices will help set you up for success with the platform.

Use the CLI to receive webhooks on your local server

When using solutions like ngrok, teams have to avoid flooding each other with unwanted webhooks. That's why we recommend using Hookdeck CLI to develop and test your webhook integrations locally.

With the CLI, each team member receives their own copy of a webhook, and the history is isolated per team member. Each team member can also listen to just the pertinent events, rather than all the webhooks received at a given URL. Events sent to the CLI are available on your dashboard and can be browsed, filtered, and replayed just like production events.

Use bookmarks for integration tests

Instead of keeping stale JSON checks in your repo, you can use your webhook event history as mock data for future integration tests. Use bookmarks to store and replay representative payloads.

Replace your webhook queue

Implementing a webhook queue on your own server when receiving events from Hookdeck is redundant. That's because Hookdeck already behaves as a push queue, eliminating the need to implement a queue of your own. To control the rate at which your server processes requests, simply set a rate limit on your destination.

Handle events synchronously

It's common knowledge that you should not take action immediately upon receiving a webhook. But with Hookdeck, you can safely perform server-side operations as soon as you receive an event. It provides a 60-second timeout window for you to process each inbound event, and return a representative response and HTTP status code. Process webhooks synchronously to make the most of Hookdeck.

Handle events in order

With or without Hookdeck, there's no guarantee what order webhooks will arrive in. That's why it's important that your destination server use its own logic to order events upon receiving them. Always use relevant data from the provider's payload, such as an updated_at value, to ensure you don't process stale requests that might overwrite more recent updates.

Implement idempotency

Most webhooks providers, including Hookdeck, operate on an "at least once" approach. This means an event may be successfully delivered more than once. Because there is no guarantee that requests will be delivered only once, actions taken on an event by your destination server should be idempotent.

Integrate with CI & CD

Using the admin API, Hookdeck can be integrated within your CI & CD workflow. We recommend creating webhooks from the API before your endpoints are deployed to avoid a situation where you've forgotten to configure a webhook.

Verify the original provider's signature

Verifying the original provider's signature before processing webhooks prevents bad actors from taking illegitimate actions on your server. Use the webhook provider's original request headers, preserved in the final payload, to perform signature verification per the provider's documentation. Hookdeck re-signs each request so you can confirm that it came from Hookdeck, but this should not be used as a replacement for verifying the original provider's signature.

Hookdeck does verify the provider's signature when using integrations that support signature verification. 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 integrations, or our "configure-your-own" integration that supports generic implementations of Basic Auth, API Keys, and HMAC signature.

Verify the Hookdeck Signature

Webhooks sent by Hookdeck are verified by calculating a digital signature. Each webhook request includes an X-Hookdeck-Signature header, generated using the workspace'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 header. If they match, the webhook was sent from Hookdeck.

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

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

app.post('/webhook', async (req, res) => {
  //Extract X-Hookdeck-Signature Header from the request
  const hmacHeader = req.get('X-Hookdeck-Signature');

  //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 header
  if (hash === hmacHeader) {
    console.log('Webhook is originating from Hookdeck');
  } else {
    console.log('Signature is invalid, rejected');