Webhooks

Cartrack Fleet API cung cấp webhook notifications để hệ thống của quý khách nhận cập nhật real-time cho nhiều loại sự kiện. Webhooks giúp tích hợp liền mạch bằng cách tự động push dữ liệu sự kiện đến endpoint quý khách chỉ định mỗi khi một sự kiện xảy ra.

Webhook Flows được hỗ trợ

Tại thời điểm hiện tại, API chỉ hỗ trợ một tập webhook events giới hạn. Webhooks chưa khả dụng cho toàn bộ sự kiện của hệ thống.

Webhook flow hiện được hỗ trợ:

• Bulk Upload Delivery Jobs: Triggered khi quá trình tạo jobs hoàn tất

Hiện chưa có webhook events hoặc data schemas nào khác được hỗ trợ. Các webhook flows bổ sung có thể được giới thiệu trong các phiên bản tiếp theo.

Security và Verification

Mọi webhook request do Cartrack gửi sẽ bao gồm HTTP header X-Webhook-Signature. Signature này cho phép quý khách xác minh request thực sự đến từ Cartrack và không bị chỉnh sửa.

Signature được tạo bằng thuật toán HMAC-SHA256 với các thành phần sau:

• Secret Key: API key của quý khách.
• Payload: Raw JSON request body (ở dạng string trước khi decode hoặc parse).

Quy trình tạo Signature

1. Encode JSON payload (raw content) thành UTF-8 string.
2. Hash payload bằng HMAC-SHA256 với API key làm secret.

Ví dụ (PHP):

$secret = 'your_api_key';
$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', json_encode($payload), $secret);   

if (hash_equals($signature, $_SERVER['X-Webhook-Signature'])) {
    // Verified request
} else {
    // Invalid signature
}

Quý khách nên luôn xác minh webhook signature trước khi xử lý bất kỳ webhook request nào để đảm bảo tính toàn vẹn dữ liệu và bảo mật.