Developers (webhook, API logs, API keys)

Đường dẫn: console.checkhq.com/developers/webhook_configs

Nó là gì?

Tiêu đề trang: Manage webhooks, API logs, and API keys. Đây là nơi cấu hình kết nối kỹ thuật giữa backend Nuvioo và Check.

Các tab

Hình: Developers: Webhooks, API logs, API keys, Component Explorer

1. Webhooks

Check gửi sự kiện (ví dụ payroll đổi trạng thái, nhân viên được tạo) tới URL của Nuvioo.

Tạo webhook: bấm Create webhook config, nhập URL (HTTPS). Check sinh ra một signing key.

Mỗi request webhook có các header:

Header	Ý nghĩa
`Check-Topic`	Chủ đề sự kiện, ví dụ `payroll`
`Check-Live`	`true` nếu từ production, `false` nếu từ sandbox
`Check-WebhookEvent-ID`	ID sự kiện, dùng để chống xử lý trùng
`Check-Signature`	HMAC-SHA256 (hex) của raw body, ký bằng signing key

Body có dạng { "event": "<loại>", "data": { ... } }.

Quy tắc khi nhận webhook:

Trả 2xx trong vòng 5 giây, kể cả với sự kiện bỏ qua. Việc xử lý nặng nên đưa vào queue.
Xác thực chữ ký bằng so sánh constant-time.
Nếu lỗi liên tục, Check tự tắt webhook (production sau 7 ngày, sandbox sau khoảng 1 ngày). Sự kiện phát sinh trong lúc tắt không được gửi bù.

Các topic quan trọng: payroll, payment, company, employee, contractor, bank_account, requirement, company_filing, pay_schedule, benefit, notification, correction.

API: POST /webhook_configs, PATCH /webhook_configs/{id} (bật/tắt), POST /webhook_configs/{id}/ping (gửi thử), GET /webhook_deliveries (lịch sử gửi).

2. API logs

Nhật ký mọi request mà API key của Nuvioo gửi tới Check: path, method, status, thời gian, header và thời gian xử lý.
Lọc theo ngày giờ, path, method, status, idempotency key.
Chỉ giữ 14 ngày, có độ trễ tới 5 phút. Chỉ Admin xem được.
Không ghi các thao tác từ Console hay Check Onboard.

3. API keys

Tạo và quản lý khóa API. Gửi kèm mọi request: Authorization: Bearer <API key>.
Key sandbox và production tách riêng. Có thể giới hạn theo IP (liên hệ Check).

4. Component Explorer

Xem thử các Check Components (giao diện nhúng như onboarding nhân viên, W-4, kết nối ngân hàng) trước khi tích hợp vào Nuvioo.

Kỹ thuật cần nhớ khi gọi API

Rate limit: sandbox 10 rps; production 10–80 rps tùy số người được trả lương mỗi tháng, tối đa 100 request đồng thời. Lỗi 429 kèm Retry-After.
Idempotency: gửi header X-Idempotency-Key (UUID) cho request tạo mới; Check nhớ kết quả trong 24 giờ.
Phân trang: response có next, previous, results.