Quản lý webhook có tại /api/v2/webhooks. Coi URL webhook và thông tin ký là secret.
Trước khi bắt đầu
Tạo API key với quyền workspace tối thiểu và xác định event family mà integration cần.
Các bước
- Mở Settings → Integrations.
- Tạo hoặc chọn webhook destination.
- Ghi event ID đã cấu hình và trạng thái endpoint.
- Gửi test request tới receiver không phải production.
- Xác nhận response và kiểm tra delivery attempt trước khi bật xử lý production.
Giữ receiver idempotent. Lưu event identifier và chỉ acknowledge sau khi validate payload. Không coi mọi application event nội bộ là customer webhook được hỗ trợ.
Cấu hình và xác minh webhook
- Tạo endpoint nhận payload, lưu event identifier trước khi trả success response.
- Trong Settings → Integrations, tạo webhook với Name, Target hook URL, Event type và tùy chọn Campaign hoặc custom interest value.
- Lưu, mở destination và chọn Test. Xác nhận receiver lưu event và API báo
success: true. - Kiểm tra Webhook events với
status_code,success,retry_count,will_retry,error_message. - Xóa hoặc cập nhật destination khi URL đổi; xóa destination không xóa delivery attempt lịch sử.
Dùng cursor pagination (limit và starting_after) cho history. Coi retry là at-least-once delivery và làm consumer idempotent.
Khôi phục lỗi
Response 4xx từ receiver thường cần sửa payload hoặc xác thực; 5xx hoặc timeout có thể retry với backoff giới hạn. Xác nhận attempt tiếp theo trong Webhook events và báo event ID cùng status đã che dữ liệu.
Tham chiếu field webhook
| Field | Bắt buộc | Ý nghĩa |
|---|---|---|
| Name | Có | Nhãn workspace cho destination. |
| Target hook URL | Có | HTTPS endpoint nhận delivery. |
| Event type | Có | Event identifier từ event-types endpoint. |
| Campaign | Tùy chọn | Giới hạn event vào một campaign khi chọn. |
| Custom interest value | Có điều kiện | Bắt buộc khi event được chọn là custom interest label. |
Xác minh delivery
Sau Test, xác nhận receiver đã lưu event ID, trả success response và không tạo record trùng khi retry. Trong Webhook events, kiểm tra status_code, success, retry_count, will_retry, error_message và timestamp_next_retry.