DEV Community

Cover image for Phân biệt Webhook và API: Điểm khác biệt cốt lõi
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Phân biệt Webhook và API: Điểm khác biệt cốt lõi

“Webhook vs API” là một trong những tìm kiếm ẩn chứa một câu hỏi thực tế hơn: nếu bạn đã từng kết nối Stripe, GitHub hoặc Slack, webhook chẳng phải cũng là một API sao? Câu trả lời ngắn gọn: webhook không đối lập với API. Webhook là một kiểu giao tiếp API chạy theo hướng ngược lại.

Dùng thử Apidog ngay hôm nay

Hướng dẫn này giải thích sự khác biệt bằng góc nhìn triển khai: ai gọi ai, khi nào nên dùng REST API, khi nào nên dùng webhook, và cách kiểm thử cả hai. Nếu bạn đang xây dựng hoặc kiểm tra tích hợp, Apidog cho phép bạn thiết kế, mô phỏng và kiểm thử cả endpoint API thông thường lẫn webhook receiver trong cùng một workspace.

Câu trả lời ngắn gọn

  • API thông thường, thường là REST API, hoạt động theo mô hình request-response. Ứng dụng của bạn gửi request, server trả response. Bạn kiểm soát thời điểm gọi.
  • Webhook hoạt động theo mô hình event-driven. Nhà cung cấp gửi HTTP request đến server của bạn khi có sự kiện xảy ra. Bạn không hỏi; bạn nhận thông báo.
  • Cả hai thường dùng HTTP, URL, header và JSON payload. Vì vậy webhook đôi khi được gọi là “reverse API” hoặc “push API”.

Nói ngắn gọn: đây không phải là “webhook đấu với API”, mà là pull vs push.

Khi nói “gọi API”, mọi người thường đang nói gì?

Trong hầu hết ngữ cảnh, “gọi API” nghĩa là ứng dụng của bạn gửi HTTP request đến một endpoint và nhận response.

Ví dụ:

GET /orders/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "id": "123",
  "status": "paid",
  "total": 490000
}
Enter fullscreen mode Exit fullscreen mode

Đây là mô hình pull. Ứng dụng của bạn quyết định khi nào cần dữ liệu.

Mô hình này phù hợp khi bạn cần:

  • Tải dữ liệu khi người dùng mở trang.
  • Tạo, cập nhật hoặc xóa tài nguyên.
  • Chạy báo cáo theo lịch của hệ thống bạn.
  • Đồng bộ dữ liệu theo yêu cầu.

Đánh đổi chính: nếu muốn biết dữ liệu đã thay đổi hay chưa, bạn phải gọi lại endpoint nhiều lần. Nếu cần ôn lại cấu trúc request/response, xem thêm hiểu cấu trúc yêu cầu API.

Webhook là gì?

Webhook là một HTTP callback do bạn cấu hình. Bạn cung cấp cho nhà cung cấp một URL, ví dụ:

https://yourapp.com/webhooks/stripe
Enter fullscreen mode Exit fullscreen mode

Khi có sự kiện xảy ra, nhà cung cấp gửi HTTP POST đến URL đó.

Ví dụ payload webhook:

POST /webhooks/stripe HTTP/1.1
Host: yourapp.com
Content-Type: application/json
Stripe-Signature: t=...,v1=...

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_123",
      "amount": 490000,
      "currency": "vnd"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Lúc này, server của bạn là bên nhận request. Nhà cung cấp là bên gọi.

Webhook là cách Stripe thông báo thanh toán đã hoàn tất, cách GitHub thông báo có commit mới được push, hoặc cách Slack thông báo một lệnh đã được chạy. Để đào sâu phần receiver, xem webhook API là gì.

Webhook và API: khác biệt cốt lõi

Tiêu chí API thông thường, ví dụ REST Webhook
Ai khởi xướng Ứng dụng của bạn Nhà cung cấp
Mô hình Request-response, pull Event-driven, push
Thời điểm chạy Khi bạn gọi Khi sự kiện xảy ra
Hướng request Bạn gọi nhà cung cấp Nhà cung cấp gọi endpoint của bạn
Phù hợp cho Dữ liệu theo yêu cầu, hành động chủ động Phản ứng với sự kiện không đoán trước
Chi phí chính Có thể phải polling Phải public, bảo mật và vận hành endpoint nhận webhook

Dòng quan trọng nhất là ai khởi xướng request. Tất cả khác biệt còn lại đều xuất phát từ đó.

“Webhook chẳng phải cũng là một API sao?”

Có, nhưng cần nói chính xác hơn.

Webhook dùng các thành phần giống API thông thường:

  • HTTP method, thường là POST
  • URL endpoint
  • Header
  • JSON body
  • Status code response

Điểm khác biệt là chiều gọi:

REST API:
Your app ---> Provider API

Webhook:
Provider ---> Your app webhook endpoint
Enter fullscreen mode Exit fullscreen mode

Vì vậy, webhook là một mô hình giao tiếp API, không phải một công nghệ tách biệt. Nhiều đội ngũ tài liệu hóa webhook cạnh REST endpoint. OpenAPI 3.1 cũng có trường webhooks để mô tả chúng. Bạn có thể xem thêm về callback và webhook của OpenAPI.

Cách hiểu đúng: khi nói “webhook vs API”, phần lớn trường hợp bạn đang so sánh API request-response với cơ chế push event của cùng một sản phẩm.

Khi nào dùng API thông thường?

Dùng API request-response khi bạn cần kiểm soát thời điểm thực thi.

Ví dụ:

  • Lấy thông tin đơn hàng khi người dùng mở màn hình chi tiết.
  • Tạo payment intent.
  • Cập nhật thông tin khách hàng.
  • Gửi tin nhắn.
  • Chạy job đồng bộ dữ liệu theo lịch.

Ví dụ gọi API bằng curl:

curl -X GET "https://api.example.com/orders/123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Enter fullscreen mode Exit fullscreen mode

Mã Node.js đơn giản:

const response = await fetch("https://api.example.com/orders/123", {
  headers: {
    Authorization: `Bearer ${process.env.API_TOKEN}`,
    Accept: "application/json"
  }
});

if (!response.ok) {
  throw new Error(`API failed: ${response.status}`);
}

const order = await response.json();
console.log(order.status);
Enter fullscreen mode Exit fullscreen mode

Khi nào dùng webhook?

Dùng webhook khi nhà cung cấp kiểm soát thời điểm sự kiện xảy ra.

Ví dụ:

  • Thanh toán thành công hoặc thất bại.
  • GitHub repository có push mới.
  • CI build hoàn tất.
  • File upload xử lý xong.
  • Người dùng ký tài liệu.
  • Subscription bị hủy.

Webhook đặc biệt hữu ích khi polling gây lãng phí. Nếu một sự kiện chỉ xảy ra vài lần mỗi ngày, việc gọi API mỗi 5 giây để kiểm tra là không hiệu quả.

Nếu lựa chọn thực tế của bạn là giữa webhook và polling, xem thêm webhooks vs polling.

Ví dụ triển khai webhook receiver

Một webhook receiver tối thiểu cần làm 4 việc:

  1. Nhận request từ nhà cung cấp.
  2. Xác minh request là hợp lệ.
  3. Xử lý event.
  4. Trả response nhanh, thường là 2xx.

Ví dụ Express:

import express from "express";

const app = express();

app.use(express.json());

app.post("/webhooks/payment", async (req, res) => {
  const event = req.body;

  try {
    switch (event.type) {
      case "payment.succeeded":
        await markOrderAsPaid(event.data.orderId);
        break;

      case "payment.failed":
        await markOrderAsFailed(event.data.orderId);
        break;

      default:
        console.log(`Unhandled event type: ${event.type}`);
    }

    res.status(200).json({ received: true });
  } catch (error) {
    console.error(error);

    // Trả non-2xx để nhà cung cấp có thể retry nếu họ hỗ trợ.
    res.status(500).json({ error: "Webhook processing failed" });
  }
});

async function markOrderAsPaid(orderId) {
  console.log(`Mark order ${orderId} as paid`);
}

async function markOrderAsFailed(orderId) {
  console.log(`Mark order ${orderId} as failed`);
}

app.listen(3000, () => {
  console.log("Webhook receiver listening on port 3000");
});
Enter fullscreen mode Exit fullscreen mode

Trong production, đừng chỉ tin payload. Bạn cần xác minh chữ ký, xử lý retry, chống xử lý trùng và ghi log đầy đủ.

API và webhook thường được dùng cùng nhau

Trong hệ thống thật, bạn hiếm khi chọn một trong hai. Bạn thường dùng cả hai.

Ví dụ với Stripe:

  1. Ứng dụng của bạn gọi API của Stripe để tạo payment intent.
  2. Stripe xử lý thanh toán.
  3. Stripe gọi webhook của bạn khi thanh toán thành công hoặc thất bại.

Luồng tổng quát:

User action
   |
   v
Your app ---- create payment ----> Provider API
   |
   v
Wait for event
   |
   v
Your webhook endpoint <---- payment succeeded ---- Provider
Enter fullscreen mode Exit fullscreen mode

API dùng để bắt đầu hành động. Webhook dùng để nhận kết quả khi hành động hoàn tất.

Đây cũng là lý do “webhook vs API” dễ gây hiểu nhầm. Với tích hợp production, câu hỏi tốt hơn là: phần nào nên pull, phần nào nên push?

Để xem mô hình thiết kế rộng hơn, đọc thêm cách xây dựng API hướng sự kiện.

Webhook vs WebSocket vs polling

Ba khái niệm này thường bị trộn lẫn:

  • Polling: ứng dụng của bạn gọi API lặp lại để kiểm tra thay đổi.
  • Webhook: nhà cung cấp gửi HTTP POST đến bạn khi có event.
  • WebSocket: hai bên giữ một kết nối liên tục để trao đổi dữ liệu hai chiều.

So sánh nhanh:

Cơ chế Cách hoạt động Phù hợp cho
Polling Hỏi lặp lại Dữ liệu thay đổi theo chu kỳ, độ trễ không quá quan trọng
Webhook Nhận thông báo theo event Thanh toán, build, push code, xử lý nền
WebSocket Kết nối liên tục hai chiều Chat, realtime dashboard, game, streaming state

Phân tích chi tiết hơn tại webhook vs WebSocket.

Checklist khi thiết kế webhook

Khi xây dựng webhook receiver, hãy kiểm tra các điểm sau:

  • Endpoint public qua HTTPS: nhà cung cấp phải gọi được URL của bạn.
  • Xác minh chữ ký: không xử lý request nếu không chứng minh được nó đến từ nhà cung cấp.
  • Idempotency: cùng một event có thể được gửi nhiều lần; xử lý trùng an toàn.
  • Trả response nhanh: nếu xử lý lâu, hãy đưa event vào queue rồi trả 200.
  • Retry-aware: hiểu chính sách retry của nhà cung cấp.
  • Logging: lưu event id, type, timestamp, status xử lý.
  • Schema rõ ràng: document payload để backend, QA và consumer cùng hiểu.
  • Monitoring: alert khi webhook lỗi liên tục.

Ví dụ idempotency đơn giản:

app.post("/webhooks/payment", async (req, res) => {
  const event = req.body;

  const alreadyProcessed = await hasProcessedEvent(event.id);

  if (alreadyProcessed) {
    return res.status(200).json({ duplicate: true });
  }

  await processEvent(event);
  await saveProcessedEvent(event.id);

  res.status(200).json({ received: true });
});
Enter fullscreen mode Exit fullscreen mode

Cách thiết kế và kiểm thử cả API lẫn webhook với Apidog

Webhook khó kiểm thử hơn API thông thường vì server của bạn phải nhận request thật. Trong khi đó, nhà cung cấp không phải lúc nào cũng tạo event test đúng thời điểm bạn cần.

Apidog giúp xử lý cả hai phía:

  • Thiết kế và kiểm thử endpoint request-response bằng request, assertion và test scenario trực quan.
  • Gửi request POST mẫu đến webhook receiver của bạn để kiểm tra handler trước khi event thật đến.
  • Tài liệu hóa webhook cùng REST endpoint bằng OpenAPI để người dùng thấy toàn bộ contract.
  • Mô phỏng và xác thực payload để giảm lỗi tích hợp giữa các hệ thống.

Một workflow thực tế:

  1. Định nghĩa REST endpoint và webhook payload.
  2. Tạo request mẫu cho API thông thường.
  3. Tạo POST request mô phỏng webhook event.
  4. Kiểm tra response code, body và side effect.
  5. Document cả REST API và webhook trong cùng workspace.

Bạn có thể tải Apidog để xây dựng và kiểm thử cả hai trong một nơi.

Câu hỏi thường gặp

Webhook có phải là API không?

Webhook là một mô hình giao tiếp API. Nó dùng HTTP, URL, header và payload giống API thông thường. Khác biệt chính là nhà cung cấp gọi endpoint của bạn thay vì bạn gọi endpoint của họ.

Có thể dùng webhook mà không cần API không?

Có thể, nhưng không phổ biến. Hầu hết workflow production gọi API để bắt đầu một hành động, sau đó dùng webhook để nhận kết quả. Xem thêm webhook API là gì.

Webhook có nhanh hơn API không?

Với phản ứng theo event, webhook thường phù hợp hơn vì bạn được thông báo khi sự kiện xảy ra, thay vì phải polling. Nhưng nếu cần lấy dữ liệu ngay tại thời điểm cụ thể, API trực tiếp vẫn là lựa chọn đúng.

Webhook có thay thế REST API không?

Không. REST API phù hợp cho request theo yêu cầu và hành động do bạn khởi tạo. Webhook phù hợp cho thông báo event. Hệ thống production thường dùng cả hai.

Webhook có an toàn không?

Webhook phơi bày một endpoint public, nên bạn cần xác minh từng request. Cách phổ biến là kiểm tra chữ ký do nhà cung cấp gửi trong header. Xem thêm xác minh chữ ký webhook.

Kết luận

“Webhook vs API” là cách đặt câu hỏi chưa chính xác. API thông thường chờ bạn gọi. Webhook gọi ngược lại server của bạn khi có sự kiện. Một bên là pull, một bên là push.

Trong tích hợp thực tế:

  • Dùng API khi bạn kiểm soát thời điểm và muốn chủ động thực hiện hành động.
  • Dùng webhook khi nhà cung cấp kiểm soát thời điểm và bạn cần phản ứng với event.
  • Dùng cả hai khi cần workflow đáng tin cậy từ lúc khởi tạo đến lúc hoàn tất.

Khi sẵn sàng triển khai, hãy thiết kế, mô phỏng và kiểm thử endpoint API cùng webhook receiver trong Apidog.

Top comments (0)