API key và webhook | NextX CLI

Viết theo CLI bản 0.3.7, ảnh chụp trên Windows PowerShell bản 0.3.5, dữ liệu thật đã được che. Xem đủ cờ lệnh tại developers.nextx.vn/docs/cli.

📌 Vị trí: Terminal → nextx keys list.

nextx keys list

1 Lệnh nextx keys list. Bảng gồm ID, tên, đầu khoá, quyền và ngày hết hạn.

Cột	Cách đọc	Việc nên làm
Đầu khoá	Vài ký tự đầu, đủ để nhận khoá. Không phải khoá đầy đủ.	Đối chiếu với hệ thống đang gọi API.
Quyền	Mã quyền, dạng `crm.contacts.view`. Dòng vàng không giới hạn là khoá có phạm vi rộng.	Thu hẹp khoá đang để không giới hạn nếu chỉ cần một phân hệ.
Hết hạn	Ngày khoá ngừng dùng. Ô trống là chưa đặt ngày trên dòng đó.	Khoá thử nghiệm nên có ngày hết hạn.
đã thu hồi	Nhãn cạnh ID. Khoá này không gọi API được nữa.	Xoá hẳn bằng `nextx keys delete <id>` khi không cần giữ lịch sử.

1. Tạo, thu hồi, xem lượt gọi

nextx keys create --name "Đọc CRM" --scopes crm.contacts.view,sales.orders.view --expires 90d
nextx keys revoke <id>
nextx keys usage <id>
nextx keys calls <id>

Lệnh	Tác dụng	Lưu ý
`keys create`	Tạo khoá mới và in khoá đúng một lần.	Chép ngay vào nơi giữ bí mật. `--expires` nhận `30d`, `6m`, `1y`. Mặc định 90 ngày.
`keys revoke`	Ngừng khoá ngay.	Ứng dụng đang gắn khoá này sẽ lỗi từ lần gọi sau.
`keys usage`	Số lượt gọi 7 ngày.	Bỏ id để xem theo khoá đang hỏi.
`keys calls`	50 lượt gọi gần nhất của một khoá.	Dùng khi cần biết khoá nào vừa gọi API.

⚠️ Đừng dán API key vào đoạn chat, ảnh chụp màn hình hoặc file NEXTX.md. Trên terminal, truyền khoá bằng biến NEXTX_API_KEY, không viết khoá vào lịch sử lệnh nếu tránh được.

2. Xem sự kiện webhook

nextx webhooks events

1 Lệnh nextx webhooks events. Cột Sự kiện, Phân hệ, Mô tả và gói PRO.

Lọc một phân hệ: nextx webhooks events --module crm. Xem mẫu payload: nextx webhooks schema <tên sự kiện>.

Việc	Lệnh	Ghi chú
Xem endpoint	`nextx webhooks endpoints list`	Các URL workspace đang nhận sự kiện.
Thêm endpoint	`nextx webhooks endpoints create <url> --events contact.created,deal.won`	Danh sách sự kiện cách nhau bằng dấu phẩy.
Đổi khoá ký	`nextx webhooks endpoints rotate-secret <id>`	Khoá cũ còn hiệu lực một thời gian để bên nhận kịp đổi.
Bắn sự kiện mẫu	`nextx webhooks trigger <event>`	Mặc định bắn tới endpoint đầu tiên nhận sự kiện đó. Chỉ định bằng `--endpoint`.
Xem lượt giao	`nextx webhooks deliveries --status failed`	Lọc `success`, `failed`, `pending`.
Gửi lại	`nextx webhooks retry <deliveryId>`	Dùng sau khi endpoint đã sửa lỗi.
Nghe về máy	`nextx webhooks listen --forward-to localhost:3000/hook`	Sự kiện thật được chuyển tới máy đang phát triển.
Kiểm chữ ký	`nextx webhooks verify`	Chạy tại máy, không gọi máy chủ NextX. Cần secret, payload và header đã nhận.

💡 nextx webhooks listen --print-json in thân sự kiện ra terminal. Chỉ thêm --print-secret khi đang sửa chữ ký, và đừng để secret nằm trong log chia sẻ.