Webhook là gì — cách Casso, Stripe, Zalo 'gõ cửa' web của bạn

Hiểu đơn giản nhất

Tưởng tượng bạn order pizza từ Now.vn.

Cách 1 — API polling (như API thường):

Cứ 5 phút bạn lại gọi điện hỏi: "Pizza đã đi chưa?". 5 phút sau gọi lại: "Đã đi chưa?". Quán bận, bạn tốn pin điện thoại. Gọi 30 lần mới nhận được câu "Đã đi rồi anh ơi".

Cách 2 — Webhook (như callback):

Bạn nói shipper: "Khi pizza tới cửa thì bấm chuông". Bạn ngồi yên làm việc khác. Pizza tới → chuông kêu → bạn ra mở cửa.

Webhook = "chuông cửa" trong thế giới web. Bạn config 1 URL với nhà cung cấp dịch vụ (Casso, Stripe, GitHub, Zalo), khi có sự kiện xảy ra, họ tự "bấm chuông" (gửi HTTP POST tới URL bạn). Bạn không cần liên tục hỏi.

Tại sao bạn cần biết

• Tự động hoá payment trong 30 phút thay vì 3 ngày. Casso webhook báo "đơn VC202600001 vừa nhận 800k" → server bạn tự đánh dấu PAID + gửi Telegram cho admin. Không cần nhân viên check sao kê bank manual.
• Tích hợp realtime giữa SaaS. User đăng ký trên Zalo → webhook Zalo OA → server bạn lưu lead → đẩy vào CRM HubSpot qua webhook khác. Cả chuỗi automation không cần code custom polling.
• Phân biệt SaaS chuẩn vs nghiệp dư khi đánh giá. SaaS không có webhook = chỉ làm việc với người, không làm việc với hệ thống khác. Đối với enterprise integration, webhook là check-list cứng.
• Hiểu được lỗi 'webhook retry' trong dashboard Stripe/Casso. "Webhook delivered" = OK. "Webhook failed (status 500)" = server bạn lỗi, cần fix.
• Audit security đúng. Webhook không verify signature là lỗ Critical (vietcodex.com vừa fix M6 — Casso webhook constant-time compare).

Anatomy của một webhook delivery

Khi có sự kiện, nhà cung cấp webhook gửi:

POST /api/webhook/casso HTTP/1.1
Host: vietcodex.com
Content-Type: application/json
secure-token: WB_xxxxxxxxxxxxxxxxxxxx
X-Casso-Event: payment.received
X-Casso-Signature: t=1716000000,v1=5257a869e7ecebeda32a...
User-Agent: Casso-Webhook/2.0
 
{
  "id": 123456,
  "tid": "FT2026000123456",
  "description": "VC2026000001",
  "amount": 800000,
  "when": "2026-05-22 10:30:00"
}

5 thành phần cần verify:

Server bạn phải:

1. Verify signature trong header
2. Parse body JSON
3. Lookup event trong DB (đã xử lý chưa? idempotency)
4. Trigger business logic (mark order PAID, gửi mail, gửi Telegram)
5. Trả về 200 OK trong < 5 giây

Security: 3 cách verify webhook authentic

1. Shared secret token (đơn giản nhất)

Nhà cung cấp gửi token cố định trong header. Bạn so với token đã config.

const incoming = req.headers.get("authorization");
const expected = process.env.CASSO_WEBHOOK_SECRET;
if (incoming !== expected) return 401;

⚠️ Phải dùng constant-time compare (crypto.timingSafeEqual), KHÔNG === thường — chống timing side-channel attack. (Đây là M6 audit vietcodex.com vừa fix.)

2. HMAC signature (chuẩn cao hơn)

Nhà cung cấp ký body bằng HMAC-SHA256 với secret, gửi chữ ký trong header. Bạn ký lại body bên mình rồi so:

import { createHmac, timingSafeEqual } from "node:crypto";
 
const body = await req.text();
const incoming = req.headers.get("x-signature");
const computed = createHmac("sha256", process.env.STRIPE_WEBHOOK_SECRET)
  .update(body)
  .digest("hex");
 
if (!timingSafeEqual(Buffer.from(incoming), Buffer.from(computed))) {
  return 401;
}

Lợi ích so với (1): kể cả attacker biết secret hash, không tự ký request giả mạo được vì không có secret gốc.

Stripe, GitHub, Slack, Zalo OA đều dùng pattern HMAC.

3. IP allowlist (bổ sung)

Chỉ accept request từ IP range của Stripe/Casso. List IP công bố trong docs nhà cung cấp.

⚠️ Đừng dùng một mình IP allowlist — IP có thể spoof trong vài kịch bản. Kết hợp với (1) hoặc (2).

Idempotency — webhook gửi 2 lần không double-charge

Webhook có thể gửi trùng vì nhiều lý do:

• Lần đầu fail (network), nhà cung cấp retry
• Server bạn xử lý xong nhưng response 500 do bug khác
• Bug của nhà cung cấp gửi nhầm 2 lần

Pattern idempotency — webhook trùng KHÔNG được tạo side-effect lần 2:

// Webhook handler
async function handleCassoWebhook(payload) {
  // Check idempotency by event ID
  const exists = await db.query.payments.findFirst({
    where: eq(payments.cassoTransactionId, payload.id),
  });
  if (exists) {
    return { ok: true, deduped: true };  // Đã xử lý — bỏ qua
  }
 
  // Process new event
  await markOrderPaid(payload.description, payload.amount);
  await db.insert(payments).values({ cassoTransactionId: payload.id, ... });
}

Idempotency key có thể là: event ID, transaction ID, hoặc combine (event_type, resource_id).

Retry mechanism — webhook không bao giờ "mất"

Nhà cung cấp tốt có retry policy:

Server bạn down 1 giờ → khi up, nhà cung cấp tự gửi lại các webhook đã miss. Bạn không mất event.

Tuy nhiên, endpoint webhook PHẢI trả 200 trong < 5 giây — không thì coi là fail. Pattern chuẩn:

export async function POST(req: Request) {
  // 1. Verify signature (10ms)
  if (!verifySignature(req)) return 401;
 
  // 2. Parse body (1ms)
  const payload = await req.json();
 
  // 3. Push job vào queue (5ms)
  await queue.add("process-casso-webhook", payload);
 
  // 4. Trả 200 NGAY (tổng < 20ms)
  return new Response("ok", { status: 200 });
}
 
// Background worker xử lý queue — có thể mất 5-30 giây

Webhook handler nhẹ + nhanh. Business logic nặng để qua queue.

Webhook phổ biến ở Việt Nam

Ví dụ thực tế: vietcodex.com tích hợp Casso

Flow thanh toán đơn hàng tại vietcodex.com:

1. Khách checkout → tạo order với status=PENDING_PAYMENT, mã đơn VC2026000001
2. Hiện QR VietQR cho khách quét → chuyển tiền với nội dung VC2026000001
3. Khách chuyển bank Vietcombank 800.000đ với nội dung kia
4. Bank thông báo Casso → Casso parse description = VC2026000001
5. Casso gửi webhook POST https://vietcodex.com/api/webhook/casso kèm secure-token
6. Server vietcodex.com:
   • Verify secure-token qua timingSafeEqual (M6 audit)
   • Parse body, tìm order VC2026000001
   • So amount khớp → mark PAID
   • Provision tenant cho khách (POST /api/admin/orders/:id/provision)
   • Gửi Telegram cho admin: "💰 Đơn 001 vừa thanh toán 800k"
   • Gửi email cho khách: "Đã nhận thanh toán, đăng nhập admin-hub"
7. Server trả 200 trong < 50ms → Casso đánh dấu webhook delivered
8. Khách thấy trang status update "Đã thanh toán" qua WebSocket (Soketi)

Toàn flow ~3-10 giây từ lúc chuyển tiền đến lúc khách thấy site update. Không người gác.

Cái gì có thể sai

Webhook vs Polling vs WebSocket — chọn cái nào?

Server-to-server → webhook. Server-to-browser → WebSocket hoặc SSE.

Tóm tắt 1 dòng

Webhook = "chuông cửa" — server bên kia gửi HTTP POST cho bạn khi có sự kiện (payment, order, user signup). Khác API thường (bạn chủ động hỏi), webhook là reactive (chờ event). Verify bằng HMAC signature (chuẩn cao) hoặc shared secret + constant-time compare. Endpoint phải nhanh + idempotent + trả 200 trong < 5 giây — business logic nặng để qua queue.

Đọc tiếp

• API là gì? Tại sao mọi app, mọi web hiện đại đều cần — webhook là pattern "API ngược" — bạn expose endpoint, server khác gọi
• Mật khẩu được "băm" thế nào trong database — HMAC signature cùng concept với password hash (one-way + có secret)
• Frontend vs Backend khác nhau ở đâu — webhook 100% là chuyện giữa 2 backend, frontend không liên quan
• HTTPS, SSL, TLS — vì sao web không có ổ khoá xanh thì khách bỏ chạy — webhook URL bắt buộc HTTPS