Bảo mật Webhook: Chữ ký HMAC, Chống Replay Attack và Đảm bảo Idempotency An toàn

Security tutorial - IT technology blog
Security tutorial - IT technology blog

Bối cảnh & Lý do: Những rủi ro tiềm ẩn đằng sau các Webhook Endpoint

Hệ thống microservices hiện đại phụ thuộc rất lớn vào các event hook từ bên ngoài. Bất cứ khi nào khách hàng mua gói đăng ký, thanh toán giỏ hàng hoặc push code, các nhà cung cấp như Stripe, Shopify và GitHub đều gửi một HTTP POST payload đến API của bạn.

Thế nhưng lỗ hổng cũng xuất phát từ đây: các ingestion endpoint tiếp nhận dữ liệu này bắt buộc phải mở công khai ra internet. Bất kỳ port mở hay route nào không được bảo vệ đều trở thành mục tiêu dò quét. Kẻ tấn công có thể giả mạo payload, mạo danh gateway của bên thứ ba, đánh cắp dữ liệu truyền tải hoặc kích hoạt hàng loạt hành động trùng lặp dây chuyền trên toàn bộ hệ thống backend của bạn.

Bảo vệ chặt chẽ các endpoint này đồng nghĩa với việc vô hiệu hóa ba vector tấn công trọng yếu:

  • Giả mạo và Can thiệp dữ liệu (Spoofing and Tampering): Kẻ xấu gửi các event giả mạo—chẳng hạn như một payload invoice.paid ngụy tạo—nhằm hưởng dịch vụ hoặc nhận hàng miễn phí. Chúng ta ngăn chặn điều này bằng chữ ký HMAC (Hash-based Message Authentication Code) SHA-256 gắn liền với một shared secret key.
  • Tấn công phát lại (Replay Attacks): Kẻ nghe lén trên mạng bắt được một request hợp lệ có chữ ký mật mã chuẩn xác, sau đó gửi phát lại vào server của bạn nhiều giờ sau đó. Dù bước kiểm tra chữ ký vẫn hợp lệ, database của bạn có thể sẽ cộng thêm tiền hoặc giao hàng hai lần. Chúng ta triệt tiêu rủi ro này bằng cách áp dụng một khoảng thời gian chấp nhận timestamp nghiêm ngặt (thông thường là 300 giây).
  • Giao nhận trùng lặp (Duplicate Delivery): Sự cố rớt mạng tạm thời hoặc cơ chế retry từ phía upstream thường kích hoạt các lượt gửi giống hệt nhau. Nếu Stripe retry 5 lần trong một giờ vì lỗi 504 gateway timeout thoáng qua, hệ thống của bạn tuyệt đối không được chạy business logic đến 5 lần. Vấn đề này được giải quyết bằng cách ghi nhận các idempotency key trong bộ nhớ cache in-memory như Redis thông qua các thao tác nguyên tử (atomic operations).

Cài đặt: Chuẩn bị môi trường và các thư viện phụ thuộc

Chúng ta sẽ xây dựng một webhook receiver sẵn sàng cho môi trường production bằng Node.js 20+, Express, và Redis 7 để thực hiện atomic lock với độ trễ cực thấp.

Khởi tạo thư mục dự án riêng biệt:

mkdir secure-webhook-receiver
cd secure-webhook-receiver
npm init -y

Cài đặt ioredis để thao tác key-value nhanh chóng và dotenv để quản lý secret runtime:

npm install express ioredis dotenv

Khởi chạy một Redis instance cục bộ bằng Docker nếu bạn chưa có sẵn:

docker run -d --name redis-webhook -p 6379:6379 redis:7-alpine

Cấu hình: Triển khai HMAC, Xác thực Timestamp và Idempotency

Có một nguyên tắc bất di bất dịch trong bảo mật webhook: không bao giờ xác thực chữ ký trên chuỗi JSON đã được parse. Việc parse payload sẽ làm thay đổi thứ tự key, chuẩn hóa khoảng trắng và loại bỏ định dạng ở cấp độ byte. Những sai lệch nhỏ đó sẽ làm mất hiệu lực của cryptographic hash ngay lập tức. Bạn bắt buộc phải ghi nhận và ký trên chính xác luồng raw byte stream nhận vào.

Lưu trữ các biến cấu hình trong file .env cục bộ. Shared secret cần một chuỗi có độ ngẫu nhiên cao (high-entropy)—lý tưởng nhất là 32 bytes (64 ký tự hex):

PORT=3000
WEBHOOK_SECRET=7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Các secret bị hardcode hoặc từ khóa từ điển ngắn sẽ khiến endpoint của bạn dễ bị tấn công brute-force offline. Khi tạo thông tin xác thực cho production, bạn có thể nhanh chóng tạo các chuỗi hex 256-bit an toàn mật mã bằng công cụ tạo mật khẩu trực tiếp trên trình duyệt tại toolcraft.app/vi/tools/security/password-generator. Do hoạt động bằng Web Crypto API phía client mà không truyền tải qua mạng, các key được tạo ra sẽ không bao giờ bị lộ ra môi trường bên ngoài.

Xây dựng toàn bộ engine xác thực bên trong server.js:

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const Redis = require('ioredis');

const app = express();
const redis = new Redis({
  host: process.env.REDIS_HOST || '127.0.0.1',
  port: parseInt(process.env.REDIS_PORT, 10) || 6379
});

// Giữ nguyên raw byte stream để phục vụ xác thực mã hóa
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

// Middleware xác thực: kiểm tra chữ ký, độ lệch timestamp và tính toàn vẹn của payload
function verifyWebhookSignature(req, res, next) {
  const signatureHeader = req.headers['x-webhook-signature'];
  const timestampHeader = req.headers['x-webhook-timestamp'];
  const secret = process.env.WEBHOOK_SECRET;

  if (!signatureHeader || !timestampHeader) {
    return res.status(401).json({ error: 'Thiếu security headers' });
  }

  // 1. Phòng chống Replay Attack: từ chối các timestamp lệch quá 300 giây
  const currentTime = Math.floor(Date.now() / 1000);
  const requestTime = parseInt(timestampHeader, 10);
  const maxToleranceSeconds = 300; // Ngưỡng lệch tối đa 5 phút

  if (isNaN(requestTime) || Math.abs(currentTime - requestTime) > maxToleranceSeconds) {
    return res.status(400).json({ error: 'Timestamp nằm ngoài khoảng thời gian cho phép' });
  }

  // 2. Tính HMAC SHA-256 trên chuỗi nối giữa timestamp và raw bytes
  const computedHex = crypto
    .createHmac('sha256', secret)
    .update(`${timestampHeader}.`)
    .update(req.rawBody)
    .digest('hex');

  // 3. So sánh hằng thời gian (constant-time) để ngăn chặn side-channel timing attack
  const signatureBuffer = Buffer.from(signatureHeader, 'hex');
  const expectedBuffer = Buffer.from(computedHex, 'hex');

  if (
    signatureBuffer.length !== expectedBuffer.length ||
    !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)
  ) {
    return res.status(403).json({ error: 'Chữ ký webhook không hợp lệ' });
  }

  next();
}

// Route tiếp nhận với atomic lock idempotency trên Redis
app.post('/api/webhooks/orders', verifyWebhookSignature, async (req, res) => {
  const eventId = req.headers['x-webhook-id'] || req.body.id;

  if (!eventId) {
    return res.status(400).json({ error: 'Thiếu idempotency event ID' });
  }

  // 4. Atomic lock: Redis SET key value EX 86400 NX
  const idempotencyKey = `webhook:processed:${eventId}`;
  const acquired = await redis.set(idempotencyKey, 'processing', 'EX', 86400, 'NX');

  if (!acquired) {
    // Event đang được xử lý hoặc đã hoàn tất; phản hồi mà không lặp lại tác vụ phụ
    return res.status(200).json({ status: 'ignored', message: 'Sự kiện đã được xử lý hoặc đang thực thi' });
  }

  try {
    // Xử lý business logic (ví dụ: giao sản phẩm số, gửi thông báo thanh toán)
    console.log(`Đang xử lý event ${eventId}:`, req.body);

    // Chuyển trạng thái từ 'processing' sang 'completed'
    await redis.set(idempotencyKey, 'completed', 'EX', 86400);

    return res.status(200).json({ status: 'success', eventId });
  } catch (error) {
    // Xóa key khi gặp lỗi bất ngờ để nhà cung cấp có thể retry thành công
    await redis.del(idempotencyKey);
    return res.status(500).json({ error: 'Lỗi xử lý nội bộ' });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook receiver đang lắng nghe trên cổng ${PORT}`);
});

Xác thực & Giám sát: Các kịch bản kiểm thử và Tiêu chuẩn Production

Trước khi đưa endpoint vào tiếp nhận traffic thực tế, hãy kiểm tra từng cơ chế bảo mật bằng các lệnh curl có chủ đích.

1. Kiểm thử Request hợp lệ có đầy đủ chữ ký

Tạo một HMAC hash hợp lệ bằng OpenSSL với Unix timestamp hiện tại và payload JSON thử nghiệm:

SECRET="7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b"
TIMESTAMP=$(date +%s)
PAYLOAD='{"id":"evt_order_9981","type":"payment.succeeded","amount":4900}'

# Tạo chữ ký HMAC-SHA256 hợp lệ
SIGNATURE=$(printf "%s.%s" "$TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

# Gửi payload đã ký
curl -i -X POST http://localhost:3000/api/webhooks/orders \
  -H "Content-Type: application/json" \
  -H "x-webhook-timestamp: ${TIMESTAMP}" \
  -H "x-webhook-signature: ${SIGNATURE}" \
  -H "x-webhook-id: evt_order_9981" \
  -d "${PAYLOAD}"

Receiver của bạn sẽ phản hồi HTTP/1.1 200 OK cùng phần body {"status":"success","eventId":"evt_order_9981"}.

2. Kiểm thử khả năng ngăn chặn Replay Attack

Mô phỏng trường hợp kẻ tấn công gửi lại traffic đã thu thập được. Hãy tạo một timestamp lùi về 10 phút (600 giây) trong quá khứ:

EXPIRED_TIMESTAMP=$(( $(date +%s) - 600 ))
EXPIRED_SIG=$(printf "%s.%s" "$EXPIRED_TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

curl -i -X POST http://localhost:3000/api/webhooks/orders \
  -H "Content-Type: application/json" \
  -H "x-webhook-timestamp: ${EXPIRED_TIMESTAMP}" \
  -H "x-webhook-signature: ${EXPIRED_SIG}" \
  -H "x-webhook-id: evt_order_9982" \
  -d "${PAYLOAD}"

Server sẽ từ chối timestamp quá hạn ngay lập tức: trả về HTTP/1.1 400 Bad Request cùng nội dung {"error":"Timestamp nằm ngoài khoảng thời gian cho phép"}.

3. Kiểm thử tính Idempotency

Gửi lại request hợp lệ ban đầu (với evt_order_9981). Do Redis đã lưu trữ key đó, ứng dụng của bạn sẽ bỏ qua bước xử lý và trả về:

{"status":"ignored","message":"Sự kiện đã được xử lý hoặc đang thực thi"}

Cơ chế đảm bảo duy nhất này giúp ngăn chặn hoàn toàn việc trừ tiền hai lần ngoài ý muốn và tránh khấu trừ trùng lặp tồn kho.

Các chỉ số giám sát liên tục

Thiết lập cảnh báo trong Prometheus, Datadog hoặc CloudWatch xoay quanh ba tín hiệu quan trọng:

  • Tỷ lệ lỗi 401/403: Mức tăng đột biến thường báo hiệu shared secret không khớp, API credential được xoay vòng nhưng chưa đồng bộ, hoặc lưu lượng probe dò quét đang hoạt động. Cần điều tra bất kỳ tỷ lệ nào vượt quá 0.1% tổng lưu lượng.
  • Tỷ lệ sự kiện trùng lặp (Duplicate Event Ratio): Tỷ lệ trùng lặp thông thường dao động ở mức cơ bản từ 1% đến 3%. Nếu con số này bất ngờ vượt quá 5%, nguyên nhân thường do downstream xử lý lâu hơn ngưỡng timeout của bên gọi (Stripe timeout sau 5 giây; GitHub cho phép 10 giây), dẫn đến kích hoạt cơ chế retry tự động không cần thiết.
  • Độ trễ tiếp nhận P95 (P95 Ingestion Latency): Duy trì thời gian phản hồi webhook dưới 250ms. Nếu các transaction database hoặc lệnh gọi API bên thứ ba kéo độ trễ tăng cao, hãy đẩy khối lượng công việc sang hàng đợi bất đồng bộ như BullMQ, SQS hoặc RabbitMQ ngay sau khi xác nhận đã nhận request.
Share: