Webhooks

WEBHOOK_SECRET=very-secret-value

timestamp.rawBody

HMAC-SHA256(secret, timestamp + "." + rawBody)

X-Webhook-Id: evt_123
X-Webhook-Timestamp: 1710000000
X-Webhook-Signature: sha256=...

{"id":"evt_123","active":true}

{
  "id": "evt_123",
  "active": true
}

Math.abs(currentTime - requestTime) <= allowedSkew

event_id = evt_123

WEBHOOK_SECRET=very-secret-value node webhook-demo.mjs

import http from "node:http";
import crypto from "node:crypto";

const PORT = Number(process.env.PORT || 3000);
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET || "very-secret-value";
const MAX_BODY_SIZE = 1024 * 1024;
const MAX_TIMESTAMP_SKEW_SECONDS = 5 * 60;

// У production це має бути PostgreSQL, Redis або інше постійне сховище.
const receivedEvents = new Map();

function readRawBody(request, limit) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    let totalSize = 0;
    let settled = false;

    request.on("data", (chunk) => {
      totalSize += chunk.length;

      if (totalSize > limit) {
        if (!settled) {
          settled = true;
          reject(new Error("BODY_TOO_LARGE"));
        }

        // Продовжуємо читати потік, щоб коректно завершити HTTP-запит.
        request.resume();
        return;
      }

      chunks.push(chunk);
    });

    request.on("end", () => {
      if (!settled) {
        settled = true;
        resolve(Buffer.concat(chunks));
      }
    });

    request.on("error", (error) => {
      if (!settled) {
        settled = true;
        reject(error);
      }
    });
  });
}

function isValidSignature(rawBody, timestampHeader, signatureHeader) {
  const timestamp = Number(timestampHeader);

  if (!Number.isInteger(timestamp)) {
    return false;
  }

  const currentTimestamp = Math.floor(Date.now() / 1000);

  if (
    Math.abs(currentTimestamp - timestamp) >
    MAX_TIMESTAMP_SKEW_SECONDS
  ) {
    return false;
  }

  const signedPayload = `${timestamp}.${rawBody.toString("utf8")}`;

  const expectedSignature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(signedPayload)
    .digest("hex");

  const receivedSignature = String(signatureHeader || "").replace(
    /^sha256=/,
    ""
  );

  const expectedBuffer = Buffer.from(expectedSignature, "utf8");
  const receivedBuffer = Buffer.from(receivedSignature, "utf8");

  if (expectedBuffer.length !== receivedBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(expectedBuffer, receivedBuffer);
}

async function processEvent(event) {
  // Тут може бути запис у базу даних, оновлення замовлення тощо.
  console.log("Обробка події:", event.id, event.type);

  await new Promise((resolve) => setTimeout(resolve, 100));

  console.log("Подію оброблено:", event.id);
}

const server = http.createServer(async (request, response) => {
  if (request.method !== "POST" || request.url !== "/webhooks/payment") {
    response.writeHead(404, { "Content-Type": "application/json" });
    response.end(JSON.stringify({ error: "Not found" }));
    return;
  }

  let rawBody;

  try {
    rawBody = await readRawBody(request, MAX_BODY_SIZE);
  } catch (error) {
    if (error.message === "BODY_TOO_LARGE") {
      response.writeHead(413, { "Content-Type": "application/json" });
      response.end(JSON.stringify({ error: "Request body is too large" }));
      return;
    }

    response.writeHead(400, { "Content-Type": "application/json" });
    response.end(JSON.stringify({ error: "Cannot read request body" }));
    return;
  }

  const timestampHeader = request.headers["x-webhook-timestamp"];
  const signatureHeader = request.headers["x-webhook-signature"];
  const eventId = request.headers["x-webhook-id"];

  if (!eventId || !timestampHeader || !signatureHeader) {
    response.writeHead(400, { "Content-Type": "application/json" });
    response.end(JSON.stringify({ error: "Missing webhook headers" }));
    return;
  }

  if (
    !isValidSignature(rawBody, timestampHeader, signatureHeader)
  ) {
    response.writeHead(401, { "Content-Type": "application/json" });
    response.end(JSON.stringify({ error: "Invalid webhook signature" }));
    return;
  }

  let event;

  try {
    event = JSON.parse(rawBody.toString("utf8"));
  } catch {
    response.writeHead(400, { "Content-Type": "application/json" });
    response.end(JSON.stringify({ error: "Invalid JSON" }));
    return;
  }

  if (event.id !== eventId) {
    response.writeHead(400, { "Content-Type": "application/json" });
    response.end(JSON.stringify({ error: "Event ID mismatch" }));
    return;
  }

  if (receivedEvents.has(eventId)) {
    response.writeHead(200, { "Content-Type": "application/json" });
    response.end(JSON.stringify({ received: true, duplicate: true }));
    return;
  }

  // У production ця перевірка та вставка мають бути атомарною.
  receivedEvents.set(eventId, {
    status: "accepted",
    receivedAt: new Date().toISOString()
  });

  // У production тут краще додати подію до надійної черги.
  setImmediate(async () => {
    try {
      await processEvent(event);

      const savedEvent = receivedEvents.get(eventId);
      if (savedEvent) {
        savedEvent.status = "processed";
      }
    } catch (error) {
      console.error("Помилка обробки події:", eventId, error);

      const savedEvent = receivedEvents.get(eventId);
      if (savedEvent) {
        savedEvent.status = "failed";
      }

      // Після 202 зовнішній сервіс уже може не повторити запит.
      // Тому production-черга повинна мати власні повторні спроби.
    }
  });

  response.writeHead(202, { "Content-Type": "application/json" });
  response.end(JSON.stringify({ received: true }));
});

server.listen(PORT, () => {
  console.log(`Webhook-сервер слухає порт ${PORT}`);
});

function sleep(milliseconds) {
  return new Promise((resolve) => setTimeout(resolve, milliseconds));
}

function shouldRetryStatus(statusCode) {
  return (
    statusCode === 408 ||
    statusCode === 425 ||
    statusCode === 429 ||
    statusCode >= 500
  );
}

function getRetryAfterMilliseconds(value) {
  if (!value) {
    return null;
  }

  const seconds = Number(value);

  if (Number.isFinite(seconds) && seconds >= 0) {
    return seconds * 1000;
  }

  const date = Date.parse(value);

  if (!Number.isNaN(date)) {
    return Math.max(0, date - Date.now());
  }

  return null;
}

export async function sendWebhook({
  url,
  event,
  secret = WEBHOOK_SECRET,
  maxAttempts = 5
}) {
  const eventId = event.id || crypto.randomUUID();
  const body = JSON.stringify({ ...event, id: eventId });

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    const timestamp = Math.floor(Date.now() / 1000);

    const signature = crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}.${body}`)
      .digest("hex");

    try {
      const result = await fetch(url, {
        method: "POST",
        headers: {
          "content-type": "application/json",
          "x-webhook-id": eventId,
          "x-webhook-timestamp": String(timestamp),
          "x-webhook-signature": `sha256=${signature}`
        },
        body,
        signal: AbortSignal.timeout(5000)
      });

      if (result.ok) {
        return {
          eventId,
          status: result.status,
          attempts: attempt
        };
      }

      if (!shouldRetryStatus(result.status) || attempt === maxAttempts) {
        throw new Error(`Webhook failed with HTTP ${result.status}`);
      }

      const retryAfter = getRetryAfterMilliseconds(
        result.headers.get("retry-after")
      );

      const exponentialDelay = 500 * 2 ** (attempt - 1);
      const jitter = Math.floor(Math.random() * 250);
      const delay = retryAfter ?? exponentialDelay + jitter;

      console.warn(
        `Webhook отримав ${result.status}; повтор через ${delay} мс`
      );

      await sleep(delay);
    } catch (error) {
      if (attempt === maxAttempts) {
        throw error;
      }

      const exponentialDelay = 500 * 2 ** (attempt - 1);
      const jitter = Math.floor(Math.random() * 250);

      console.warn(
        `Помилка надсилання webhook: ${error.message}; ` +
          `повтор через ${exponentialDelay + jitter} мс`
      );

      await sleep(exponentialDelay + jitter);
    }
  }

  throw new Error("Webhook was not delivered");
}

import { sendWebhook } from "./webhook-demo.mjs";

await sendWebhook({
  url: "http://localhost:3000/webhooks/payment",
  event: {
    id: "evt_1001",
    type: "payment.succeeded",
    data: {
      orderId: "order_42",
      amount: 12500
    }
  }
});

500 мс
1000 мс
2000 мс
4000 мс
8000 мс

webhook_events
--------------
event_id        UNIQUE
event_type
payload
status
received_at
processed_at

const event = JSON.parse(requestBody);
const body = JSON.stringify(event);
verifySignature(body);