Authentication & Verification

const HOOKDECK_WEBHOOK_SECRET = process.env.HOOKDECK_WEBHOOK_SECRET;

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", HOOKDECK_WEBHOOK_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 || (hmacHeader2 && hash === hmacHeader2)) {
    console.log("Webhook is originating from Hookdeck");
    res.sendStatus(200);
  } else {
    console.log("Signature is invalid, rejected");
    res.sendStatus(403);
  }
});

npm i @hookdeck/sdk

import { verifyWebhookSignature } from "@hookdeck/sdk/webhooks";

const HOOKDECK_WEBHOOK_SECRET = process.env.HOOKDECK_WEBHOOK_SECRET;

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

app.post("/webhook", async (req, res) => {
  const verified = await verifyWebhookSignature({
    headers: req.headers,
    rawBody: req.rawBody,
    signingSecret: HOOKDECK_WEBHOOK_SECRET}
  );

  if(verified === true) {
    console.log("Webhook is originating from Hookdeck");
    res.sendStatus(200);
  }
  else {
    console.log("Signature is invalid, rejected");
    res.sendStatus(403);
  }
});

See the TypeScript quickstart code on GitHub.

import os
from datetime import datetime
import json
import logging
import hashlib
import hmac
import base64
from flask import Flask, request

logging.basicConfig(level=logging.INFO, handlers=[logging.StreamHandler()])

app = Flask(__name__)
app.logger.setLevel(logging.INFO)

HOOKDECK_WEBHOOK_SECRET = os.getenv("HOOKDECK_WEBHOOK_SECRET")


def verify_webhook(request):
    if HOOKDECK_WEBHOOK_SECRET is None:
        app.logger.warn(
            "No HOOKDECK_WEBHOOK_SECRET found in environment variables. Skipping verification."
        )
        return False

    # Extract x-hookdeck-signature and x-hookdeck-signature-2 headers from the request
    hmac_header = request.headers.get("x-hookdeck-signature")
    hmac_header2 = request.headers.get("x-hookdeck-signature-2")

    # Create a hash based on the raw body
    hash = base64.b64encode(
        hmac.new(
            HOOKDECK_WEBHOOK_SECRET.encode(), request.data, hashlib.sha256
        ).digest()
    ).decode()

    # Compare the created hash with the value of the x-hookdeck-signature
    # Also check x-hookdeck-signature-2 header in case the secret was rolled
    return hash == hmac_header or (hmac_header2 and hash == hmac_header2)


@app.route("/<path:path>", methods=["POST"])
def handle(path):
    app.logger.info(
        "webhook_received %s %s",
        datetime.now().isoformat(),
        json.dumps(request.json, indent=2),
    )

    if not verify_webhook(request):
        return {"status": "UNAUTHORIZED"}, 403
    else:
        return {"status": "ACCEPTED"}, 200


if __name__ == "__main__":
    app.run(debug=True, port=3031)

See the Python quickstart code on GitHub.

package main

import (
  "bytes"
  "crypto/hmac"
  "crypto/sha256"
  "encoding/base64"
  "encoding/json"
  "fmt"
  "io"
  "log"
  "net/http"
  "os"

  "github.com/gin-gonic/gin"
)

func verifyPayload(jsonBody string, headers http.Header) bool {
  secret := os.Getenv("HOOKDECK_WEBHOOK_SECRET")
  if secret == "" {
    log.Println("No HOOKDECK_WEBHOOK_SECRET found in environment variables. Skipping verification.")
    return true
  }

  hmacHeader := headers.Get("x-hookdeck-signature")
  hmacHeader2 := headers.Get("x-hookdeck-signature-2")

  hash := hmac.New(sha256.New, []byte(secret))
  hash.Write([]byte(jsonBody))
  expectedHash := base64.StdEncoding.EncodeToString(hash.Sum(nil))

  if expectedHash == hmacHeader ||
    (hmacHeader2 != "" && expectedHash == hmacHeader2) {
    return true
  }

  return false
}

func main() {
  r := gin.Default()
  r.POST("/*path", func(c *gin.Context) {
    bodyAsByteArray, err := io.ReadAll(c.Request.Body)
    jsonBody := string(bodyAsByteArray)

    if err != nil {
      c.JSON(http.StatusInternalServerError, gin.H{
        "message": "could not get request body data",
      })
      return
    }

    verified := verifyPayload(jsonBody, c.Request.Header)

    if !verified {
      c.JSON(http.StatusUnauthorized, gin.H{
        "message": "invalid payload",
      })
      return
    }

    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, []byte(jsonBody), "", "  "); err != nil {
      log.Printf("Failed to format JSON: %v", err)
      c.JSON(http.StatusInternalServerError, gin.H{
        "message": "failed to format JSON",
      })
      return
    }
    log.Printf("webhook_received: %v", prettyJSON.String())

    c.JSON(http.StatusOK, gin.H{
      "status": "ACCEPTED",
    })
  })

  port := os.Getenv("PORT")
  if port == "" {
    port = "3032"
  }

  fmt.Printf("🪝 Server running at http://localhost:%s", port)
  r.Run(fmt.Sprintf(":%s", port))
}

See the Go quickstart code on GitHub.

using System.Security.Cryptography;
using System.Text;

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

const string HOOKDECK_SIGNATURE_HEADER = "X-Hookdeck-Signature";
const string HOOKDECK_WEBHOOK_SECRET_CONFIG_KEY = "inbound:HookdeckWebhookSecret";

string WEBHOOK_SECRET = builder.Configuration[HOOKDECK_WEBHOOK_SECRET_CONFIG_KEY] ?? string.Empty;

static bool VerifyHmacWebhookSignature(HttpContext context, string webhookSecret, string rawBody)
{
    if(string.IsNullOrEmpty(webhookSecret))
    {
        Console.WriteLine("WARNING: Missing webhook secret. Skipping verification.");
        return true;
    }

    string? hmacHeader = context.Request.Headers[HOOKDECK_SIGNATURE_HEADER].FirstOrDefault();

    if (string.IsNullOrEmpty(hmacHeader))
    {
        Console.WriteLine("Missing HMAC headers");
        return false;
    }
    HMACSHA256 hmac = new(Encoding.UTF8.GetBytes(webhookSecret));
    string hash = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(rawBody)));

    return hash.Equals(hmacHeader);
}

app.MapPost("/{**path}", async (string? path, HttpContext context) =>
{
    using StreamReader reader = new StreamReader(context.Request.Body);
    string rawBody = await reader.ReadToEndAsync();
    
    bool verified = VerifyHmacWebhookSignature(context, WEBHOOK_SECRET, rawBody);
    if(!verified)
    {
        return Results.Unauthorized();
    }

    Console.WriteLine(new
    {
        webhook_received = DateTime.UtcNow.ToString("o"),
        body = rawBody
    });
    
    return Results.Json(new {
        STATUS = "ACCEPTED"
    });
});

app.UseRouting();

app.Run();

See the C# quickstart code on GitHub.