Webhooks

#!/usr/bin/env bash
# Subscribe a public HTTPS URL (port 443) to events, keep the secret, send the test ping.
# Up to 3 subscriptions per sandbox. Needs WEBHOOK_URL, for example a Zapier Catch Hook URL.
set -euo pipefail
BASE="${ATLAS_BASE:-https://automationatlas.io/labs/api/v1}"
: "${ATLAS_OFFICE_KEY:?run: source atlas-keys.env}"
: "${WEBHOOK_URL:?set WEBHOOK_URL to your public https:// endpoint}"

created=$(curl -sS -X POST "$BASE/webhooks" \
  -H "Authorization: Bearer $ATLAS_OFFICE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: subscribe-orders-1" \
  -d "$(jq -n --arg url "$WEBHOOK_URL" '{url: $url, events: ["office.sales_order.received"], description: "new orders"}')")
echo "$created" | jq '.data | {id, status, url_host, events}'

# The whsec_ secret is returned once. Replaying the same Idempotency-Key never repeats it (secret is null).
secret=$(jq -r '.data.secret // empty' <<<"$created")
[ -n "$secret" ] && (umask 077; printf '%s' "$secret" > atlas-webhook-secret.txt; chmod 600 atlas-webhook-secret.txt) || echo "no secret in this response (a replay?)" >&2
ID=$(jq -r '.data.id' <<<"$created")

# The subscription starts as pending_verification and activates when this ping gets a 2xx.
curl -sS -X POST "$BASE/webhooks/$ID/test" -H "Authorization: Bearer $ATLAS_OFFICE_KEY" | jq .data
curl -sS "$BASE/webhooks/$ID" -H "Authorization: Bearer $ATLAS_OFFICE_KEY" | jq '.data | {status, consecutive_failures, last_error_class}'

// Subscribe a public HTTPS URL (port 443) to events, keep the secret, send the test ping (Node 20+).
// Up to 3 subscriptions per sandbox.  Run: WEBHOOK_URL=https://... node 06-subscribe-webhook.mjs
import { chmodSync, writeFileSync } from "node:fs";

const BASE = process.env.ATLAS_BASE ?? "https://automationatlas.io/labs/api/v1";
const headers = { Authorization: `Bearer ${process.env.ATLAS_OFFICE_KEY}`, "Content-Type": "application/json" };

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "subscribe-orders-1" },
  body: JSON.stringify({
    url: process.env.WEBHOOK_URL,
    events: ["office.sales_order.received"], // or ["*"] for every event type
    description: "new orders",
  }),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${res.status} ${error.code} ${JSON.stringify(error.details ?? {})}`);

// The whsec_ secret is returned once. Replaying the same Idempotency-Key never repeats it (secret is null).
if (data.secret) {
  writeFileSync("atlas-webhook-secret.txt", data.secret, { mode: 0o600 });
  chmodSync("atlas-webhook-secret.txt", 0o600); // `mode` only applies to a new file
} else console.warn("no secret in this response (a replay?)");
console.log(data.id, data.status, data.url_host);

// The subscription starts as pending_verification and activates when this ping gets a 2xx.
const ping = await fetch(`${BASE}/webhooks/${data.id}/test`, { method: "POST", headers });
console.log("test ping", ping.status);

"""Subscribe a public HTTPS URL (port 443) to events, keep the secret, send the test ping.

Up to 3 subscriptions per sandbox.  pip install requests
Run: WEBHOOK_URL=https://... python 06-subscribe-webhook.py
"""
import os

import requests

BASE = os.environ.get("ATLAS_BASE", "https://automationatlas.io/labs/api/v1")
HEADERS = {"Authorization": f"Bearer {os.environ['ATLAS_OFFICE_KEY']}"}

res = requests.post(
    f"{BASE}/webhooks",
    headers={**HEADERS, "Idempotency-Key": "subscribe-orders-1"},
    json={
        "url": os.environ["WEBHOOK_URL"],
        "events": ["office.sales_order.received"],  # or ["*"] for every event type
        "description": "new orders",
    },
    timeout=30,
)
body = res.json()
if not res.ok:
    err = body["error"]
    raise SystemExit(f"{res.status_code} {err['code']} {err.get('details')}")
hook = body["data"]

# The whsec_ secret is returned once. Replaying the same Idempotency-Key never repeats it (secret is null).
if hook.get("secret"):
    fd = os.open("atlas-webhook-secret.txt", os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    with os.fdopen(fd, "w") as f:
        f.write(hook["secret"])
    os.chmod("atlas-webhook-secret.txt", 0o600)  # the mode above only applies to a new file
else:
    print("no secret in this response (a replay?)")
print(hook["id"], hook["status"], hook["url_host"])

# The subscription starts as pending_verification and activates when this ping gets a 2xx.
ping = requests.post(f"{BASE}/webhooks/{hook['id']}/test", headers=HEADERS, timeout=30)
print("test ping", ping.status_code)

// Receive and verify an Atlas Labs webhook (Node 20+, no dependencies).
// Standard Webhooks: headers webhook-id, webhook-timestamp, webhook-signature.
// signature = "v1," + base64(HMAC-SHA256(key, `${id}.${timestamp}.${rawBody}`)), where key is
// the base64-decoded part of your whsec_ secret. During the 24 h after rotate-secret the header
// holds two space-separated values ("v1,<new> v1,<old>"); accept either.
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const SECRET = process.env.ATLAS_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_S = 300;

export function verify(secret, headers, rawBody, nowS = Math.floor(Date.now() / 1000)) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const header = headers["webhook-signature"];
  if (!id || !timestamp || !header) return false;
  if (Math.abs(nowS - Number(timestamp)) > TOLERANCE_S) return false; // stale or replayed
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`, "utf8").digest();
  return header.split(" ").some((part) => {
    const [version, value] = part.split(",");
    if (version !== "v1" || !value) return false;
    const given = Buffer.from(value, "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const seen = new Set(); // deliveries are at-least-once: de-duplicate on the event id
  createServer((req, res) => {
    const chunks = [];
    req.on("data", (c) => chunks.push(c));
    req.on("end", () => {
      const rawBody = Buffer.concat(chunks).toString("utf8"); // verify the RAW body, before JSON.parse
      if (!verify(SECRET, req.headers, rawBody)) {
        res.writeHead(401).end();
        return;
      }
      const event = JSON.parse(rawBody);
      if (!seen.has(event.id)) {
        seen.add(event.id);
        console.log(event.type, event.id, event.links?.self);
      }
      res.writeHead(200).end(); // reply 2xx quickly: the timeout is 5 s and 5 consecutive failures disable the subscription
    });
  }).listen(Number(process.env.PORT ?? 3000));
}

"""Receive and verify an Atlas Labs webhook (Python 3.9+, standard library only).

Standard Webhooks: headers webhook-id, webhook-timestamp, webhook-signature.
signature = "v1," + base64(HMAC-SHA256(key, f"{id}.{timestamp}.{raw_body}")), where key is
the base64-decoded part of your whsec_ secret. During the 24 h after rotate-secret the header
holds two space-separated values ("v1,<new> v1,<old>"); accept either.
"""
import base64
import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ.get("ATLAS_WEBHOOK_SECRET", "")  # whsec_...
TOLERANCE_S = 300
seen = set()  # deliveries are at-least-once: de-duplicate on the event id


def verify(secret, headers, raw_body: bytes, now=None) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    header = headers.get("webhook-signature")
    if not (msg_id and timestamp and header):
        return False
    if abs((now or time.time()) - int(timestamp)) > TOLERANCE_S:  # stale or replayed
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for part in header.split(" "):
        version, _, value = part.partition(",")
        if version == "v1" and hmac.compare_digest(value, expected):
            return True
    return False


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get("content-length", 0)))  # verify the RAW body
        if not verify(SECRET, self.headers, raw):
            self.send_response(401)
            self.end_headers()
            return
        event = json.loads(raw)
        if event["id"] not in seen:
            seen.add(event["id"])
            print(event["type"], event["id"], event.get("links", {}).get("self"))
        self.send_response(200)  # reply 2xx quickly: the timeout is 5 s and 5 consecutive failures disable the subscription
        self.end_headers()


if __name__ == "__main__":
    HTTPServer(("0.0.0.0", int(os.environ.get("PORT", 3000))), Handler).serve_forever()

#!/usr/bin/env bash
# Check one saved delivery by hand with openssl (handy when debugging a Zapier/Make/n8n receiver).
# Usage: ./07-verify-webhook.sh whsec_... "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP" 'raw-body-exactly-as-received' 'v1,base64sig'
set -euo pipefail
secret=$1 id=$2 timestamp=$3 body=$4 header=$5
hexkey=$(printf '%s' "${secret#whsec_}" | base64 -d | xxd -p -c 256)
expected=$(printf '%s.%s.%s' "$id" "$timestamp" "$body" \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$hexkey" -binary | base64)
for part in $header; do
  [ "${part#v1,}" = "$expected" ] && { echo "signature OK"; exit 0; }
done
echo "signature MISMATCH" >&2; exit 1