Webhooks

curl -X POST https://api.usenexio.com/api/v1/webhooks \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/nexio",
    "events": ["run.completed", "run.failed", "run.cancelled"],
    "description": "Production run callbacks",
    "payload_mode": "full",
    "auth_token": "gw_example_token"
  }'

import os
import requests

resp = requests.post(
    "https://api.usenexio.com/api/v1/webhooks",
    headers={"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]},
    json={
        "url": "https://hooks.example.com/nexio",
        "events": ["run.completed", "run.failed", "run.cancelled"],
        "description": "Production run callbacks",
        "payload_mode": "full",
        "auth_token": "gw_example_token",
    },
    timeout=30,
)
resp.raise_for_status()
endpoint = resp.json()
print(endpoint["id"])
# Store endpoint["secret"] in your secret manager now. It is never returned again.

const resp = await fetch("https://api.usenexio.com/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NEXIO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/nexio",
    events: ["run.completed", "run.failed", "run.cancelled"],
    description: "Production run callbacks",
    payload_mode: "full",
    auth_token: "gw_example_token",
  }),
});
if (!resp.ok) {
  throw new Error(`create webhook failed: ${resp.status} ${await resp.text()}`);
}
const endpoint = await resp.json();
console.log(endpoint.id);
// Store endpoint.secret in your secret manager now. It is never returned again.

"""Nexio webhook verification using only the Python 3 standard library."""

from __future__ import annotations

import base64
import hashlib
import hmac
import json
import sys
import threading
from collections.abc import Mapping, Sequence

MAX_TIMESTAMP_SKEW_SECONDS = 5 * 60


class WebhookVerifier:
    def __init__(self, initial_delivery_ids: Sequence[str] = ()) -> None:
        # This in-memory set demonstrates the delivery-ID deduplication contract.
        # Production receivers need a durable, shared store with an atomic insert.
        self._seen_delivery_ids = set(initial_delivery_ids)
        self._seen_lock = threading.Lock()

    def verify(
        self,
        headers: Mapping[str, str],
        raw_body: bytes,
        secrets: Sequence[str],
        now_unix: int,
    ) -> None:
        """Verify exact request bytes and record the delivery ID once."""
        if not isinstance(raw_body, bytes):
            raise TypeError("raw_body must contain the exact request bytes")

        delivery_id = _get_header(headers, "X-Nexio-Delivery").strip()
        timestamp_header = _get_header(headers, "X-Nexio-Timestamp").strip()
        signature_header = _get_header(headers, "X-Nexio-Signature")
        if not delivery_id or not timestamp_header or not signature_header:
            raise ValueError("missing required Nexio webhook header")

        timestamp, signatures = _parse_signature_header(signature_header)
        if timestamp != timestamp_header:
            raise ValueError("signature timestamp does not match X-Nexio-Timestamp")
        if not timestamp.isascii() or not timestamp.isdecimal():
            raise ValueError("invalid signature timestamp")

        timestamp_unix = int(timestamp)
        if abs(now_unix - timestamp_unix) > MAX_TIMESTAMP_SKEW_SECONDS:
            raise ValueError("signature timestamp is outside the five-minute window")

        message = timestamp.encode("ascii") + b"." + raw_body
        matched = False
        for secret in secrets:
            expected = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
            for candidate in signatures:
                if len(candidate) == 64 and _is_hex(candidate):
                    matched = hmac.compare_digest(expected, candidate.lower()) or matched
        if not matched:
            raise ValueError("invalid webhook signature")

        with self._seen_lock:
            if delivery_id in self._seen_delivery_ids:
                raise ValueError("duplicate webhook delivery")
            self._seen_delivery_ids.add(delivery_id)


def _get_header(headers: Mapping[str, str], wanted_name: str) -> str:
    wanted = wanted_name.lower()
    for name, value in headers.items():
        if name.lower() == wanted:
            return str(value)
    return ""


def _parse_signature_header(header: str) -> tuple[str, list[str]]:
    timestamp = ""
    timestamp_seen = False
    signatures: list[str] = []
    for raw_part in header.split(","):
        part = raw_part.strip()
        if "=" not in part:
            continue
        key, value = part.split("=", 1)
        value = value.strip()
        if key == "t":
            if timestamp_seen:
                raise ValueError("duplicate signature timestamp")
            timestamp_seen = True
            timestamp = value
        elif key == "v1" and value:
            signatures.append(value)
    if not timestamp or not signatures:
        raise ValueError("malformed X-Nexio-Signature header")
    return timestamp, signatures


def _is_hex(value: str) -> bool:
    try:
        bytes.fromhex(value)
    except ValueError:
        return False
    return True


def run_corpus_case(input_case: Mapping[str, object]) -> dict[str, object]:
    verifier = WebhookVerifier(input_case.get("seen_delivery_ids", ()))
    try:
        verifier.verify(
            input_case["headers"],
            base64.b64decode(input_case["raw_body_base64"], validate=True),
            input_case["verification_secrets"],
            int(input_case["now_unix"]),
        )
    except (TypeError, ValueError) as error:
        return {"accepted": False, "error": str(error)}
    return {"accepted": True, "error": ""}


if __name__ == "__main__":
    case = json.load(sys.stdin)
    print(json.dumps(run_corpus_case(case), separators=(",", ":")))

'use strict'

const { createHmac, timingSafeEqual } = require('node:crypto')
const fs = require('node:fs')

const MAX_TIMESTAMP_SKEW_SECONDS = 5 * 60

class WebhookVerifier {
  constructor(initialDeliveryIDs = []) {
    // This in-memory set demonstrates the delivery-ID deduplication contract.
    // Production receivers need a durable, shared store with an atomic insert.
    this.seenDeliveryIDs = new Set(initialDeliveryIDs)
  }

  verify(headers, rawBody, secrets, nowUnix) {
    if (!Buffer.isBuffer(rawBody)) {
      throw new TypeError('rawBody must be a Buffer containing the exact request bytes')
    }

    const deliveryID = getHeader(headers, 'X-Nexio-Delivery').trim()
    const timestampHeader = getHeader(headers, 'X-Nexio-Timestamp').trim()
    const signatureHeader = getHeader(headers, 'X-Nexio-Signature')
    if (!deliveryID || !timestampHeader || !signatureHeader) {
      throw new Error('missing required Nexio webhook header')
    }

    const { timestamp, signatures } = parseSignatureHeader(signatureHeader)
    if (timestamp !== timestampHeader) {
      throw new Error('signature timestamp does not match X-Nexio-Timestamp')
    }
    if (!/^\d+$/.test(timestamp)) {
      throw new Error('invalid signature timestamp')
    }

    const timestampUnix = Number(timestamp)
    if (!Number.isSafeInteger(timestampUnix) || Math.abs(nowUnix - timestampUnix) > MAX_TIMESTAMP_SKEW_SECONDS) {
      throw new Error('signature timestamp is outside the five-minute window')
    }

    const presented = signatures
      .filter((signature) => /^[0-9a-fA-F]{64}$/.test(signature))
      .map((signature) => Buffer.from(signature, 'hex'))

    let matched = false
    for (const secret of secrets) {
      const expected = createHmac('sha256', Buffer.from(secret, 'utf8'))
        .update(timestamp, 'utf8')
        .update('.', 'utf8')
        .update(rawBody)
        .digest()
      for (const candidate of presented) {
        matched = timingSafeEqual(expected, candidate) || matched
      }
    }
    if (!matched) {
      throw new Error('invalid webhook signature')
    }

    if (this.seenDeliveryIDs.has(deliveryID)) {
      throw new Error('duplicate webhook delivery')
    }
    this.seenDeliveryIDs.add(deliveryID)
  }
}

function getHeader(headers, wantedName) {
  const wanted = wantedName.toLowerCase()
  for (const [name, value] of Object.entries(headers)) {
    if (name.toLowerCase() === wanted) {
      return String(value)
    }
  }
  return ''
}

function parseSignatureHeader(header) {
  let timestamp = ''
  let timestampSeen = false
  const signatures = []
  for (const rawPart of header.split(',')) {
    const part = rawPart.trim()
    const separator = part.indexOf('=')
    if (separator < 1) continue
    const key = part.slice(0, separator)
    const value = part.slice(separator + 1).trim()
    if (key === 't') {
      if (timestampSeen) throw new Error('duplicate signature timestamp')
      timestampSeen = true
      timestamp = value
    } else if (key === 'v1' && value) {
      signatures.push(value)
    }
  }
  if (!timestamp || signatures.length === 0) {
    throw new Error('malformed X-Nexio-Signature header')
  }
  return { timestamp, signatures }
}

function runCorpusCase(input) {
  const verifier = new WebhookVerifier(input.seen_delivery_ids || [])
  try {
    verifier.verify(
      input.headers,
      Buffer.from(input.raw_body_base64, 'base64'),
      input.verification_secrets,
      input.now_unix,
    )
    return { accepted: true, error: '' }
  } catch (error) {
    return { accepted: false, error: error.message }
  }
}

if (require.main === module) {
  const input = JSON.parse(fs.readFileSync(0, 'utf8'))
  process.stdout.write(`${JSON.stringify(runCorpusCase(input))}\n`)
}

module.exports = { WebhookVerifier, runCorpusCase }

import { createHmac, timingSafeEqual } from 'node:crypto'

const MAX_TIMESTAMP_SKEW_SECONDS = 5 * 60

export class WebhookVerifier {
  // This in-memory set demonstrates the delivery-ID deduplication contract.
  // Production receivers need a durable, shared store with an atomic insert.
  private readonly seenDeliveryIDs: Set<string>

  constructor(initialDeliveryIDs: Iterable<string> = []) {
    this.seenDeliveryIDs = new Set(initialDeliveryIDs)
  }

  verify(headers: Record<string, string>, rawBody: Buffer, secrets: string[], nowUnix: number): void {
    if (!Buffer.isBuffer(rawBody)) {
      throw new TypeError('rawBody must be a Buffer containing the exact request bytes')
    }

    const deliveryID = getHeader(headers, 'X-Nexio-Delivery').trim()
    const timestampHeader = getHeader(headers, 'X-Nexio-Timestamp').trim()
    const signatureHeader = getHeader(headers, 'X-Nexio-Signature')
    if (!deliveryID || !timestampHeader || !signatureHeader) {
      throw new Error('missing required Nexio webhook header')
    }

    const { timestamp, signatures } = parseSignatureHeader(signatureHeader)
    if (timestamp !== timestampHeader) {
      throw new Error('signature timestamp does not match X-Nexio-Timestamp')
    }
    if (!/^\d+$/.test(timestamp)) {
      throw new Error('invalid signature timestamp')
    }

    const timestampUnix = Number(timestamp)
    if (!Number.isSafeInteger(timestampUnix) || Math.abs(nowUnix - timestampUnix) > MAX_TIMESTAMP_SKEW_SECONDS) {
      throw new Error('signature timestamp is outside the five-minute window')
    }

    const presented = signatures
      .filter((signature) => /^[0-9a-fA-F]{64}$/.test(signature))
      .map((signature) => Buffer.from(signature, 'hex'))

    let matched = false
    for (const secret of secrets) {
      const expected = createHmac('sha256', Buffer.from(secret, 'utf8'))
        .update(timestamp, 'utf8')
        .update('.', 'utf8')
        .update(rawBody)
        .digest()
      for (const candidate of presented) {
        matched = timingSafeEqual(expected, candidate) || matched
      }
    }
    if (!matched) {
      throw new Error('invalid webhook signature')
    }

    if (this.seenDeliveryIDs.has(deliveryID)) {
      throw new Error('duplicate webhook delivery')
    }
    this.seenDeliveryIDs.add(deliveryID)
  }
}

function getHeader(headers: Record<string, string>, wantedName: string): string {
  const wanted = wantedName.toLowerCase()
  for (const [name, value] of Object.entries(headers)) {
    if (name.toLowerCase() === wanted) {
      return String(value)
    }
  }
  return ''
}

function parseSignatureHeader(header: string): { timestamp: string; signatures: string[] } {
  let timestamp = ''
  let timestampSeen = false
  const signatures: string[] = []
  for (const rawPart of header.split(',')) {
    const part = rawPart.trim()
    const separator = part.indexOf('=')
    if (separator < 1) continue
    const key = part.slice(0, separator)
    const value = part.slice(separator + 1).trim()
    if (key === 't') {
      if (timestampSeen) throw new Error('duplicate signature timestamp')
      timestampSeen = true
      timestamp = value
    } else if (key === 'v1' && value) {
      signatures.push(value)
    }
  }
  if (!timestamp || signatures.length === 0) {
    throw new Error('malformed X-Nexio-Signature header')
  }
  return { timestamp, signatures }
}

// Package webhookverify is a partner-facing Nexio webhook verifier.
package webhookverify

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"net/http"
	"strconv"
	"strings"
	"sync"
	"time"
)

const maxTimestampSkew = 5 * time.Minute

// Verifier verifies webhook signatures and rejects duplicate delivery IDs.
type Verifier struct {
	mu              sync.Mutex
	seenDeliveryIDs map[string]struct{}
}

// NewVerifier returns a verifier with an optional set of already-seen delivery
// IDs. The in-memory set demonstrates the delivery-ID deduplication contract.
// Production receivers need a durable, shared store with an atomic insert.
func NewVerifier(initialDeliveryIDs ...string) *Verifier {
	seen := make(map[string]struct{}, len(initialDeliveryIDs))
	for _, deliveryID := range initialDeliveryIDs {
		seen[deliveryID] = struct{}{}
	}
	return &Verifier{seenDeliveryIDs: seen}
}

// Verify authenticates the exact raw request bytes and records the delivery ID.
func (v *Verifier) Verify(headers http.Header, rawBody []byte, secrets [][]byte, now time.Time) error {
	deliveryID := strings.TrimSpace(headers.Get("X-Nexio-Delivery"))
	timestampHeader := strings.TrimSpace(headers.Get("X-Nexio-Timestamp"))
	signatureHeader := headers.Get("X-Nexio-Signature")
	if deliveryID == "" || timestampHeader == "" || signatureHeader == "" {
		return errors.New("missing required Nexio webhook header")
	}

	timestamp, signatures, err := parseSignatureHeader(signatureHeader)
	if err != nil {
		return err
	}
	if timestamp != timestampHeader {
		return errors.New("signature timestamp does not match X-Nexio-Timestamp")
	}
	if !isDecimal(timestamp) {
		return errors.New("invalid signature timestamp")
	}

	timestampUnix, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return errors.New("invalid signature timestamp")
	}
	nowUnix := now.Unix()
	if timestampUnix < nowUnix-int64(maxTimestampSkew/time.Second) || timestampUnix > nowUnix+int64(maxTimestampSkew/time.Second) {
		return errors.New("signature timestamp is outside the five-minute window")
	}

	matched := false
	for _, secret := range secrets {
		mac := hmac.New(sha256.New, secret)
		_, _ = mac.Write([]byte(timestamp))
		_, _ = mac.Write([]byte("."))
		_, _ = mac.Write(rawBody)
		expected := mac.Sum(nil)
		for _, signature := range signatures {
			candidate, decodeErr := hex.DecodeString(signature)
			if decodeErr == nil && len(candidate) == sha256.Size {
				matched = hmac.Equal(expected, candidate) || matched
			}
		}
	}
	if !matched {
		return errors.New("invalid webhook signature")
	}

	v.mu.Lock()
	defer v.mu.Unlock()
	if _, duplicate := v.seenDeliveryIDs[deliveryID]; duplicate {
		return errors.New("duplicate webhook delivery")
	}
	v.seenDeliveryIDs[deliveryID] = struct{}{}
	return nil
}

func parseSignatureHeader(header string) (string, []string, error) {
	var timestamp string
	timestampSeen := false
	var signatures []string
	for _, rawPart := range strings.Split(header, ",") {
		key, value, found := strings.Cut(strings.TrimSpace(rawPart), "=")
		if !found {
			continue
		}
		value = strings.TrimSpace(value)
		switch key {
		case "t":
			if timestampSeen {
				return "", nil, errors.New("duplicate signature timestamp")
			}
			timestampSeen = true
			timestamp = value
		case "v1":
			if value != "" {
				signatures = append(signatures, value)
			}
		}
	}
	if timestamp == "" || len(signatures) == 0 {
		return "", nil, errors.New("malformed X-Nexio-Signature header")
	}
	return timestamp, signatures, nil
}

func isDecimal(value string) bool {
	if value == "" {
		return false
	}
	for _, character := range value {
		if character < '0' || character > '9' {
			return false
		}
	}
	return true
}

import time

from flask import Flask, request

from verify_webhook import WebhookVerifier

app = Flask(__name__)
verifier = WebhookVerifier()
SECRETS = ["whsec_example000000000000000000000000000000000000000000000000000000000"]


@app.post("/nexio")
def nexio_webhook():
    raw_body = request.get_data(cache=False)
    try:
        verifier.verify(dict(request.headers), raw_body, SECRETS, int(time.time()))
    except ValueError as error:
        if str(error) == "duplicate webhook delivery":
            return "", 200
        return "", 401
    enqueue(request.headers["X-Nexio-Event"], raw_body)  # your queue
    return "", 204

import { createServer } from "node:http";
// Save the JavaScript verifier as verify_webhook.cjs: it is a CommonJS module.
import { WebhookVerifier } from "./verify_webhook.cjs";

const verifier = new WebhookVerifier();
const secrets = ["whsec_example000000000000000000000000000000000000000000000000000000000"];

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk: Buffer) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks);
    try {
      verifier.verify(req.headers, rawBody, secrets, Math.floor(Date.now() / 1000));
    } catch (error) {
      const duplicate = (error as Error).message === "duplicate webhook delivery";
      res.writeHead(duplicate ? 200 : 401).end();
      return;
    }
    enqueue(String(req.headers["x-nexio-event"]), rawBody); // your queue
    res.writeHead(204).end();
  });
}).listen(8080);

curl -X POST https://api.usenexio.com/api/v1/webhooks/2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12/rotate-secret \
  -H "Authorization: Bearer $NEXIO_API_KEY"

import os
import requests

endpoint_id = "2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12"
resp = requests.post(
    f"https://api.usenexio.com/api/v1/webhooks/{endpoint_id}/rotate-secret",
    headers={"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]},
    timeout=30,
)
resp.raise_for_status()
rotation = resp.json()
print(rotation["previous_secret_expires_at"])

const endpointId = "2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12";
const resp = await fetch(
  `https://api.usenexio.com/api/v1/webhooks/${endpointId}/rotate-secret`,
  { method: "POST", headers: { Authorization: `Bearer ${process.env.NEXIO_API_KEY}` } },
);
if (!resp.ok) {
  throw new Error(`rotate failed: ${resp.status} ${await resp.text()}`);
}
const rotation = await resp.json();
console.log(rotation.previous_secret_expires_at);

curl "https://api.usenexio.com/api/v1/webhooks/2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12/deliveries?status=dead_letter" \
  -H "Authorization: Bearer $NEXIO_API_KEY"

curl -X POST https://api.usenexio.com/api/v1/webhooks/2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12/deliveries/5e2b8d47-91c3-5a6f-b0e4-3c7d1f9a8e25/resend \
  -H "Authorization: Bearer $NEXIO_API_KEY"

import os
import requests

base = "https://api.usenexio.com/api/v1/webhooks/2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12"
headers = {"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]}

cursor = None
while True:
    params = {"status": "dead_letter"}
    if cursor:
        params["cursor"] = cursor
    page = requests.get(f"{base}/deliveries", headers=headers, params=params, timeout=30)
    page.raise_for_status()
    body = page.json()
    for delivery in body["deliveries"]:
        resend = requests.post(f"{base}/deliveries/{delivery['id']}/resend", headers=headers, timeout=30)
        resend.raise_for_status()
        print(resend.json())
    cursor = body.get("next_cursor")
    if not cursor:
        break

const base = "https://api.usenexio.com/api/v1/webhooks/2f7c1b9e-4a3d-4e8b-9c61-0d5a7e3f8b12";
const headers = { Authorization: `Bearer ${process.env.NEXIO_API_KEY}` };

let cursor: string | undefined;
do {
  const params = new URLSearchParams({ status: "dead_letter" });
  if (cursor) params.set("cursor", cursor);
  const page = await fetch(`${base}/deliveries?${params}`, { headers });
  if (!page.ok) throw new Error(`list failed: ${page.status} ${await page.text()}`);
  const body = await page.json();
  for (const delivery of body.deliveries) {
    const resend = await fetch(`${base}/deliveries/${delivery.id}/resend`, { method: "POST", headers });
    if (!resend.ok) throw new Error(`resend failed: ${resend.status} ${await resend.text()}`);
    console.log(await resend.json());
  }
  cursor = body.next_cursor;
} while (cursor);