Webhooks

curl -X POST https://swaglists.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com/webhooks/print",
    "enabled_events": ["order.in_production", "order.shipped", "order.delivered", "order.on_hold", "order.failed", "order.canceled"],
    "description": "Order status sync"
  }'

const res = await fetch("https://swaglists.com/api/v1/webhook_endpoints", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/webhooks/print", enabled_events: ["*"] }),
});
const endpoint = await res.json();
console.log(endpoint.id, endpoint.secret); // store the secret now — it is not shown again

endpoint = requests.post(
    "https://swaglists.com/api/v1/webhook_endpoints",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"url": "https://example.com/webhooks/print", "enabled_events": ["*"]},
).json()
print(endpoint["id"], endpoint["secret"])  # store the secret now — it is not shown again

// npm install standardwebhooks express
import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.WEBHOOK_SECRET); // "whsec_…"

app.post("/webhooks/print", express.raw({ type: "*/*" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString("utf8"), req.headers); // throws if invalid or too old
  } catch {
    return res.status(400).send("invalid signature");
  }
  enqueue(event); // process asynchronously
  res.sendStatus(204);
});

app.listen(3000);

# pip install standardwebhooks flask
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

app = Flask(__name__)
wh = Webhook(os.environ["WEBHOOK_SECRET"])  # "whsec_…"

@app.post("/webhooks/print")
def webhook():
    try:
        event = wh.verify(request.get_data(), dict(request.headers))  # raw bytes
    except Exception:
        return "invalid signature", 400
    enqueue(event)  # process asynchronously
    return "", 204

<?php
// composer require standard-webhooks/standard-webhooks
require __DIR__ . '/vendor/autoload.php';

use StandardWebhooks\Webhook;

$payload = file_get_contents('php://input');
$headers = [
    'webhook-id'        => $_SERVER['HTTP_WEBHOOK_ID'] ?? '',
    'webhook-timestamp' => $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '',
    'webhook-signature' => $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '',
];

try {
    $event = (new Webhook(getenv('WEBHOOK_SECRET')))->verify($payload, $headers);
} catch (Exception $e) {
    http_response_code(400);
    exit('invalid signature');
}

enqueue($event); // process asynchronously
http_response_code(204);

# gem install standardwebhooks  (Rails controller shown)
require "standardwebhooks"

class PrintWebhooksController < ActionController::API
  WEBHOOK = StandardWebhooks::Webhook.new(ENV.fetch("WEBHOOK_SECRET"))

  def create
    event = WEBHOOK.verify(request.raw_post, {
      "webhook-id" => request.headers["webhook-id"],
      "webhook-timestamp" => request.headers["webhook-timestamp"],
      "webhook-signature" => request.headers["webhook-signature"],
    })
    PrintWebhookJob.perform_later(event) # process asynchronously
    head :no_content
  rescue StandardError
    head :bad_request
  end
end

// go get github.com/standard-webhooks/standard-webhooks/libraries/go
package main

import (
	"io"
	"log"
	"net/http"
	"os"

	standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go"
)

func main() {
	wh, err := standardwebhooks.NewWebhook(os.Getenv("WEBHOOK_SECRET"))
	if err != nil {
		log.Fatal(err)
	}
	http.HandleFunc("/webhooks/print", func(w http.ResponseWriter, r *http.Request) {
		payload, err := io.ReadAll(r.Body)
		if err != nil {
			http.Error(w, "bad request", http.StatusBadRequest)
			return
		}
		if err := wh.Verify(payload, r.Header); err != nil {
			http.Error(w, "invalid signature", http.StatusBadRequest)
			return
		}
		enqueue(payload) // process asynchronously
		w.WriteHeader(http.StatusNoContent)
	})
	log.Fatal(http.ListenAndServe(":3000", nil))
}

import { createHmac, timingSafeEqual } from "node:crypto";

/** headers: a Fetch `Headers` object or Node's lowercase `req.headers`. Returns the parsed event or throws. */
export function verifyWebhook(rawBody, headers, secret, toleranceSeconds = 300) {
  const get = (name) => (typeof headers.get === "function" ? headers.get(name) : headers[name]);
  const id = get("webhook-id");
  const timestamp = get("webhook-timestamp");
  const signatures = get("webhook-signature");
  if (!id || !timestamp || !signatures) throw new Error("missing webhook headers");
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    throw new Error("timestamp outside tolerance");
  }
  const key = Buffer.from(secret.startsWith("whsec_") ? secret.slice(6) : secret, "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();
  for (const entry of signatures.split(" ")) {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) continue;
    const received = Buffer.from(signature, "base64");
    if (received.length === expected.length && timingSafeEqual(received, expected)) return JSON.parse(rawBody);
  }
  throw new Error("invalid signature");
}

// Next.js route handler (app/api/print-webhooks/route.js)
export async function POST(request) {
  const raw = await request.text(); // raw body BEFORE parsing
  let event;
  try {
    event = verifyWebhook(raw, request.headers, process.env.WEBHOOK_SECRET);
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
  await enqueue(event);
  return new Response(null, { status: 204 });
}

import base64, hashlib, hmac, json, time

def verify_webhook(raw: bytes, headers, secret: str, tolerance: int = 300) -> dict:
    h = {k.lower(): v for k, v in headers.items()}
    msg_id, ts, signatures = h.get("webhook-id"), h.get("webhook-timestamp"), h.get("webhook-signature")
    if not (msg_id and ts and signatures):
        raise ValueError("missing webhook headers")
    if not ts.isdigit() or abs(int(time.time()) - int(ts)) > tolerance:
        raise ValueError("timestamp outside tolerance")
    key = base64.b64decode(secret[6:] if secret.startswith("whsec_") else secret)
    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.".encode() + raw, hashlib.sha256).digest()).decode()
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return json.loads(raw)
    raise ValueError("invalid signature")

# Flask: event = verify_webhook(request.get_data(), request.headers, os.environ["WEBHOOK_SECRET"])

<?php
function verify_webhook(string $raw, array $headers, string $secret, int $tolerance = 300): array {
    $h = array_change_key_case($headers, CASE_LOWER);
    $id = $h['webhook-id'] ?? '';
    $ts = $h['webhook-timestamp'] ?? '';
    $signatures = $h['webhook-signature'] ?? '';
    if ($id === '' || $ts === '' || $signatures === '') throw new RuntimeException('missing webhook headers');
    if (!ctype_digit($ts) || abs(time() - (int) $ts) > $tolerance) throw new RuntimeException('timestamp outside tolerance');
    $key = base64_decode(str_starts_with($secret, 'whsec_') ? substr($secret, 6) : $secret, true);
    $expected = base64_encode(hash_hmac('sha256', "{$id}.{$ts}.{$raw}", $key, true));
    foreach (explode(' ', $signatures) as $entry) {
        [$version, $signature] = array_pad(explode(',', $entry, 2), 2, '');
        if ($version === 'v1' && hash_equals($expected, $signature)) return json_decode($raw, true);
    }
    throw new RuntimeException('invalid signature');
}

// $event = verify_webhook(file_get_contents('php://input'), getallheaders(), getenv('WEBHOOK_SECRET'));