Chuyển tới nội dung chính

Webhooks

Webhooks cho phép Cohost gửi sự kiện chủ động đến hệ thống bên thứ 3 khi có các thay đổi quan trọng (ví dụ: booking, thanh toán, đồng bộ lịch).

Scope: Tập trung vào việc tích hợp bên thứ 3/đối tác với Cohost qua Webhooks.
Thường được dùng kết hợp với External API Guide và iCal Sync để đồng bộ hai chiều.

Lưu ý: Danh sách event và payload cụ thể được định nghĩa chi tiết trong spec backend (OpenAPI / tài liệu nội bộ) và có thể thay đổi theo từng integration. Phần này mô tả khái niệm chung.

1. Tổng quan​

  • Thay vì bên thứ 3 phải polling API thường xuyên để kiểm tra thay đổi, Cohost có thể gửi HTTP request đến endpoint do bên thứ 3 cấu hình.
  • Ví dụ các nhóm sự kiện thường gặp:
    • Booking được tạo/cập nhật/hủy.
    • Thanh toán thành công/thất bại.
    • Đồng bộ lịch hoàn tất hoặc có lỗi.

2. Cấu hình Webhook Endpoint (khái quát)​

Luồng cấu hình (có thể khác nhau tuỳ integration):

  1. Bên thứ 3 cung cấp một hoặc nhiều URL webhook (vd qua Admin UI/API riêng).
  2. Cohost lưu thông tin:
    • URL.
    • Danh sách event quan tâm.
    • Secret key (nếu dùng chữ ký HMAC).
  3. Khi có sự kiện, Cohost gửi request tới URL tương ứng.

3. Hình thức request​

Thông thường Cohost sẽ:

  • Gửi request HTTP POST với body JSON.
  • Bao gồm:
    • event_type (tên event).
    • data (payload chính, ví dụ thông tin booking).
    • id / timestamp (giúp idempotent và logging).
  • Có thể kèm header xác thực:
    • Ví dụ: X-Signature (HMAC), X-Webhook-Id, …

Chi tiết format và cơ chế ký sẽ được mô tả cụ thể trong tài liệu webhook từng đối tác.

4. Yêu cầu đối với bên thứ 3​

Bên thứ 3 nên:

  • Đảm bảo endpoint:
    • Hỗ trợ HTTPS.
    • Trả về 2xx nếu xử lý thành công.
  • Xử lý idempotent:
    • Lưu id hoặc event_id để tránh xử lý trùng nếu Cohost retry.
  • Xử lý retry:
    • Cohost có thể retry khi gặp lỗi mạng / non-2xx.
    • Thiết kế endpoint sao cho nhận nhiều lần cùng một event vẫn an toàn.

5. Kết hợp với API Polling​

Webhooks thường được dùng kết hợp với API:

  • Khi nhận webhook, bên thứ 3:
    • Có thể gọi lại các endpoint của Cohost (booking, payments, listings, …) để lấy thông tin chi tiết.
  • Điều này giúp payload webhook có thể gọn hơn, và giảm rủi ro lộ thông tin không cần thiết.

Trong bối cảnh External Integration:

  • Webhook mang thông tin “có thay đổi” (event booking/payment/calendar).
  • External API cung cấp các endpoint chi tiết:
    • GET /api/v1/external/bookings
    • GET /api/v1/external/listings
    • Các endpoint khác theo spec external-openapi.json.

Pattern khuyến nghị cho đối tác:

  1. Nhận webhook từ Cohost.
  2. Validate chữ ký/HMAC (nếu có).
  3. Lưu event_id để đảm bảo idempotent.
  4. Gọi lại External API để kéo dữ liệu chi tiết.

6. Tài liệu chi tiết cho từng integration​

Với mỗi đối tác/thị trường, Cohost sẽ:

  • Cung cấp danh sách event cụ thể (event_type).
  • Định nghĩa payload mẫu cho từng event.
  • Mô tả cơ chế bảo mật (HMAC, IP whitelist, API Key, …).

Các tài liệu này sẽ được cung cấp riêng theo từng integration và nên được đọc cùng với trang này, ví dụ:

  • docs/04_PhanTich_ThirdParty_API.md
  • Tài liệu integration riêng cho từng OTA/đối tác (Dayladau, v.v.)