Webhook Là Gì?

Webhook (còn được gọi là Reverse API hoặc Web Callback) là một phương thức cho phép một ứng dụng tự động gửi dữ liệu real-time sang ứng dụng khác ngay khi có sự kiện cụ thể xảy ra. Thay vì bạn phải chủ động hỏi “có gì mới không?”, webhook sẽ tự báo cho bạn biết khi có việc cần xử lý.

Nghĩa đơn giản: nếu API là bạn gọi điện hỏi, thì webhook là người kia nhắn tin cho bạn. API yêu cầu bạn chủ động request, webhook tự động push dữ liệu khi event xảy ra.

Cách hoạt động của webhook rất trực quan: ứng dụng nhận (destination) đăng ký một URL endpoint tại ứng dụng gửi (source). Khi sự kiện xảy ra, source tự động gửi HTTP POST request chứa dữ liệu đến URL đã đăng ký. Destination nhận được, xử lý và thực hiện hành động tương ứng.

API Là Gì? Nhắc Lại Nhanh

API (Application Programming Interface) là giao diện cho phép hai ứng dụng giao tiếp hai chiều thông qua chu kỳ request – response, thường qua giao thức HTTP. Với API, bạn có thể thực hiện đầy đủ thao tác CRUD: Create, Read, Update, Delete trên tài nguyên của hệ thống khác.

Nếu bạn cần ôn lại chi tiết hơn, hãy xem bài API là gì? Giới thiệu API cơ bản và ứng dụng trong DevOps trên vnhte.

So Sánh Webhook và API: Sự Khác Biệt Cốt Lõi

Điểm khác biệt quan trọng nhất nằm ở chiều giao tiếp và cách kích hoạt:

• API — giao tiếp hai chiều (bidirectional). Bạn request, server response. Bạn chủ động quyết định khi nào lấy dữ liệu.
• Webhook — giao tiếp một chiều (unidirectional). Server tự động push dữ liệu khi event xảy ra. Bạn chỉ việc nhận và xử lý.

Một cách so sánh thực tế: bạn đặt mua hàng online. Với API, bạn liên tục mở app kiểm tra “giao chưa?”. Với webhook, bạn nhận notification “đã giao thành công” — không cần kiểm tra.

Bảng So Sánh Chi Tiết

Webhook Hoạt Động Như Thế Nào? Ví Dụ Thực Tế

Ví dụ 1: Stripe gửi thông báo khi thanh toán thành công

Khi khách hàng thanh toán qua Stripe, bạn không cần liên tục gọi API Stripe để kiểm tra “có payment mới không?”. Thay vào đó, bạn đăng ký webhook endpoint tại Stripe. Khi payment thành công, Stripe tự động gửi POST request đến endpoint của bạn:

{
  "id": "evt_1ABC123",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1ABC123",
      "amount": 200000,
      "currency": "vnd",
      "status": "succeeded"
    }
  },
  "created": 1700000000
}

Server của bạn nhận payload này, xác minh signature, rồi tự động cập nhật trạng thái đơn hàng — không cần polling, không cần chờ.

Ví dụ 2: GitHub webhook khi có push mới

Khi ai đó push code lên repository, GitHub gửi webhook đến CI/CD pipeline (như Jenkins, GitHub Actions). Pipeline tự động trigger build, chạy test, deploy — toàn bộ quy trình bắt đầu từ một webhook push.

Ví dụ 3: Slack Incoming Webhook

Slack cung cấp Incoming Webhook cho phép bạn gửi message tự động vào channel. Khi server monitoring phát hiện website down, nó gửi POST request đến Slack webhook URL, và team nhận alert ngay trên channel — không cần ai phải chủ động kiểm tra dashboard.

API Hoạt Động Như Thế Nào? Ví Dụ Thực Tế

Ví dụ 1: Weather API — Dữ liệu thay đổi liên tục

Ứng dụng thời tiết cần gọi API mỗi khi user mở app, vì dữ liệu thay đổi liên tục theo thời gian và vị trí. Webhook không phù hợp ở đây — bạn cần chủ động query theo yêu cầu cụ thể của người dùng.

curl "https://api.openweathermap.org/data/2.5/weather?q=Ho+Chi+Minh&appid=YOUR_KEY"

Ví dụ 2: CRUD thao tác trên database

Khi bạn cần tạo, cập nhật, hoặc xóa tài nguyên, API là lựa chọn duy nhất. Webhook chỉ gửi thông báo một chiều — không thể modify dữ liệu ở đầu nhận:

# Tạo user mới qua REST API
POST /api/users
{
  "name": "Nguyễn Văn A",
  "email": "vana@example.com",
  "role": "developer"
}

# Cập nhật user
PUT /api/users/123
{
  "role": "senior-developer"
}

# Xóa user
DELETE /api/users/123

Ví dụ 3: Pagination và filtering

API cho phép bạn query linh hoạt — lọc theo field, phân trang, sắp xếp. Webhook không có khả năng này, vì bạn chỉ nhận những gì source quyết định gửi.

# Lấy danh sách user, page 2, sort theo tên
GET /api/users?page=2&sort=name&role=developer

Webhook vs API Polling: Khi Nào Dùng Cái Nào?

Một pattern phổ biến khi cần dữ liệu real-time là API polling — gọi API lặp đi lặp lại theo interval để kiểm tra dữ liệu mới. Polling hoạt động, nhưng có nhiều hạn chế:

• Tiêu tốn tài nguyên — gửi request liên tục dù không có dữ liệu mới.
• Độ trễ — dữ liệu chỉ cập nhật ở lần polling tiếp theo, không phải real-time.
• Rate limiting — nhiều API giới hạn số request, polling dễ vượt giới hạn.
• Code phức tạp — cần xử lý retry, error, so sánh dữ liệu cũ/mới.

Webhook giải quyết tất cả vấn đề trên: không request thừa, dữ liệu đến ngay khi event xảy ra, không lo rate limit, code đơn giản hơn nhiều.

Nhưng polling vẫn có chỗ đứng của nó. Khi source không hỗ trợ webhook, hoặc khi bạn cần lấy dữ liệu lịch sử (webhook chỉ nhận event mới), polling là lựa chọn duy nhất.

Ưu Điểm và Nhược Điểm Của Webhook

Ưu điểm

• Real-time — dữ liệu đến ngay khi event xảy ra, không độ trễ.
• Tiết kiệm tài nguyên — không request thừa, server chỉ hoạt động khi có event.
• Triển khai đơn giản — chỉ cần đăng ký URL endpoint, nhận POST request.
• Chi phí thấp — không tốn chi phí API call lặp lại, không lo rate limit.
• Phù hợp automation — tự động trigger workflow khi event xảy ra.

Nhược điểm

• Một chiều — chỉ nhận dữ liệu, không thể query, modify, hay delete.
• Rủi ro mất event — nếu source down khi event xảy ra, dữ liệu bị mất nếu không có retry mechanism.
• Không phải app nào cũng hỗ trợ — nhiều dịch vụ chỉ cung cấp API, không có webhook.
• Debug khó hơn — khi webhook fail, bạn chỉ nhận status code (200, 404, 500…), không có error message chi tiết.
• Security — endpoint public có thể bị abuse, cần xác minh payload signature.

Ưu Điểm và Nhược Điểm Của API

Ưu điểm

• Linh hoạt — CRUD đầy đủ, query, filter, pagination, sort theo ý muốn.
• Hai chiều — gửi request, nhận response, xử lý error chi tiết.
• Phổ biến — gần như mọi dịch vụ web hiện đại đều cung cấp API.
• Client kiểm soát — bạn quyết định khi nào lấy dữ liệu, retry khi fail.
• Đa dạng kiến trúc — REST, GraphQL, gRPC, WebSocket… phù hợp nhiều use case.

Nhược điểm

• Không real-time — dữ liệu chỉ có khi bạn request, luôn có độ trễ.
• Polling tốn tài nguyên — gọi lặp lại liên tục dù không có dữ liệu mới.
• Phức tạp triển khai — mỗi API khác nhau về auth, rate limit, pagination, error handling.
• Chi phí — nhiều API tính phí per request, polling đẩy chi phí lên cao.

Khi Nào Nên Dùng Webhook?

• Nhận thông báo real-time — payment thành công, deployment xong, ticket mới, alert monitoring.
• Đồng bộ dữ liệu event-driven — user mới đăng ký, đơn hàng mới, subscription thay đổi.
• Trigger workflow tự động — CI/CD pipeline, email automation, Slack/Discord notification.
• Tiết kiệm tài nguyên — thay vì polling mỗi 30 giây, chỉ nhận dữ liệu khi thực sự có thay đổi.
• Tích hợp với SaaS — Stripe, GitHub, Shopify, Slack đều hỗ trợ webhook mạnh mẽ.

Khi Nào Nên Dùng API?

• Thao tác CRUD trên dữ liệu — tạo, đọc, cập nhật, xóa tài nguyên.
• Query linh hoạt — filter, search, pagination, sort theo nhiều tiêu chí.
• Dữ liệu thay đổi liên tục — thời tiết, giá chứng khoán, vị trí GPS.
• Source không hỗ trợ webhook — nhiều hệ thống legacy chỉ có API.
• Cần dữ liệu lịch sử — webhook chỉ nhận event mới, API cho phép truy xuất dữ liệu cũ.

Pattern Kết Hợp: Webhook + API — Tốt Nhất Cả Hai Thế Giới

Trong thực tế, hệ thống production hiếm khi dùng chỉ webhook hoặc chỉ API. Pattern phổ biến nhất là kết hợp cả hai:

• Webhook nhận event — “có payment mới thành công!”
• API lấy chi tiết — gọi API để lấy đầy đủ thông tin payment, customer, metadata.

Ví dụ workflow Stripe:

# 1. Webhook nhận event "payment thành công"
# Endpoint: POST /webhooks/stripe
# Payload chỉ chứa event type + payment ID

# 2. Server gọi API Stripe để lấy chi tiết đầy đủ
GET /v1/payment_intents/pi_1ABC123

# 3. Xử lý dữ liệu đầy đủ, cập nhật database, gửi email confirmation

Pattern này tận dụng ưu điểm của cả hai: webhook cho real-time notification, API cho dữ liệu chi tiết và linh hoạt. Nhiều hệ thống monitoring như Prometheus và Grafana cũng dùng pattern tương tự — alert qua webhook, query metric qua API.

Best Practices Khi Triển Khai Webhook

1. Luôn Xác Minh Signature

Endpoint webhook là public — ai cũng có thể gửi POST request đến. Hầu hết các dịch vụ (Stripe, GitHub, Shopify) ký payload bằng HMAC. Bạn phải xác minh signature trước khi xử lý:

import hmac, hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

2. Xử Lý Retry và Idempotency

Source có thể gửi lại webhook nếu không nhận được response 2xx. Endpoint của bạn phải idempotent — xử lý cùng một event nhiều lần cho cùng kết quả. Dùng event ID để deduplicate:

processed_events = set()

def handle_webhook(event):
    if event["id"] in processed_events:
        return {"status": "already_processed"}
    processed_events.add(event["id"])
    # Xử lý event...
    return {"status": "ok"}

3. Trả Về 200 Nhanh, Xử Lý Bất Đồng Bộ

Source thường timeout nếu endpoint không trả 200 trong vài giây. Pattern tốt nhất là nhận webhook, lưu vào queue, trả 200 ngay, rồi xử lý bất đồng bộ:

from queue import Queue

webhook_queue = Queue()

def handle_webhook(request):
    webhook_queue.put(request.json)
    return {"status": "received"}, 200  # Trả ngay

def worker():
    while True:
        event = webhook_queue.get()
        process_event(event)  # Xử lý chậm ở background

4. Log và Monitor Webhook

Webhook fail im lặng — không có error message chi tiết. Luôn log payload, response status, processing time. Dùng hệ thống monitoring và logging để theo dõi webhook health.

5. Dùng HTTPS và Giới Hạn IP

Endpoint webhook phải dùng HTTPS. Nếu có thể, giới hạn request chỉ từ IP range của source (Stripe publish IP range, GitHub cũng vậy). Đây là lớp bảo vệ thêm bên cạnh signature verification.

Các Dịch Vụ Sử Dụng Webhook Phổ Biến

• Stripe — payment events (succeeded, failed, refunded, subscription renewed).
• GitHub — push, pull request, issue, release events.
• Shopify — order created, order updated, product updated.
• Slack — incoming webhook cho notification tự động vào channel.
• Discord — tương tự Slack, gửi message tự động qua webhook URL.
• Twilio — SMS received, call status updated.
• AWS SNS/SQS — event notification giữa các service trong cloud architecture.

Webhook Là Subset Của API — Nhưng Không Thể Thay Thế Nhau

Một hiểu lầm phổ biến là “webhook tốt hơn API” hoặc ngược lại. Thực tế, webhook là một subset của API — nó là một loại API đặc biệt (event-driven API). Hai cái này không cạnh tranh, mà bổ sung cho nhau.

API cho bạn khả năng query, modify, và giao tiếp hai chiều — điều webhook không làm được. Webhook cho bạn real-time notification và tiết kiệm tài nguyên — điều API polling không tối ưu. Hệ thống tốt nhất dùng cả hai, mỗi cái cho đúng use case.

Kết Luận

Hiểu rõ sự khác biệt giữa webhook và API là kỹ năng cơ bản cho bất kỳ developer hay DevOps engineer nào. Tóm lại: dùng webhook khi cần real-time notification và tiết kiệm tài nguyên, dùng API khi cần thao tác dữ liệu linh hoạt và query theo yêu cầu. Trong production, pattern kết hợp webhook + API là cách tiếp cận tối ưu nhất.

Nếu bạn đang xây dựng hệ thống event-driven hoặc tích hợp với SaaS platform, webhook là công cụ không thể thiếu. Và nếu bạn cần dữ liệu lịch sử, thao tác CRUD, hoặc query linh hoạt — API vẫn là backbone của mọi hệ thống.

Tham Khảo

• Zapier – Webhook vs. API: Differences + When to Use Each
• Merge – Webhooks vs REST APIs: When to Use One Over the Other
• GeeksforGeeks – Webhook vs. API Polling in System Design