Cấu trúc của một yêu cầu Webhook
Webhook là một phương thức phổ biến để các hệ thống truyền tải thông tin sự kiện theo thời gian thực. Khi một sự kiện xảy ra ở hệ thống nguồn, một yêu cầu HTTP (thường là POST, PUT, PATCH, GET, hoặc DELETE) sẽ được gửi đến URL đích đã cấu hình. Để hiểu và xử lý chính xác các yêu cầu này, nhà phát triển cần nắm rõ cấu trúc của chúng, bao gồm phương thức HTTP, các tiêu đề (headers) truyền tải siêu dữ liệu, và phần thân (body) chứa dữ liệu sự kiện thực tế.
Việc nắm bắt cấu trúc thô của yêu cầu trước khi hệ thống phía máy chủ thực hiện phân tích cú pháp (parsing) là rất quan trọng. Nhiều lỗi tích hợp xảy ra do sự khác biệt trong cách xử lý khoảng trắng, thứ tự các trường dữ liệu, hoặc định dạng mã hóa giữa hệ thống gửi và hệ thống nhận.
Vai trò của tiêu đề và định dạng phần thân Webhook
Các tiêu đề trong yêu cầu webhook cung cấp thông tin ngữ cảnh quan trọng cho máy chủ tiếp nhận. Tiêu đề xác định kiểu nội dung (chẳng hạn như Content-Type: application/json hoặc Content-Type: application/x-www-form-urlencoded), các thông tin định danh hệ thống gửi, và các tham số bảo mật.
Phần thân của webhook thường được truyền tải dưới hai định dạng phổ biến:
- JSON: Dữ liệu được cấu trúc dưới dạng các cặp khóa-giá trị hoặc mảng. Khi phân tích cú pháp JSON bằng các hàm tiêu chuẩn như
JSON.parse, thứ tự các trường và khoảng trắng nguyên bản sẽ bị thay đổi do quá trình tái cấu trúc dữ liệu. - URL-encoded: Dữ liệu biểu mẫu được mã hóa dưới dạng chuỗi truy vấn. Định dạng này yêu cầu các ký tự đặc biệt phải được mã hóa phần trăm (percent-encoding) chính xác.
Nếu phần thân webhook sử dụng các định dạng khác, chúng sẽ được giữ nguyên dưới dạng văn bản thuần túy.
Chữ ký Webhook và dấu thời gian bảo mật
Để đảm bảo an toàn, các nhà cung cấp webhook thường gửi kèm các tiêu đề chứa chữ ký mã hóa (signature) và dấu thời gian (timestamp). Các tiêu đề này thường có tên chứa các từ khóa như signature, hmac, hoặc digest.
Tuy nhiên, cần phân biệt rõ giữa việc nhận diện tiêu đề chữ ký và việc xác thực tính hợp lệ của yêu cầu:
- Nhận diện: Công cụ giúp phát hiện sự hiện diện của các tiêu đề chữ ký hoặc dấu thời gian phổ biến trong yêu cầu được dán vào.
- Xác thực thực tế: Việc xác minh tính xác thực của một webhook đòi hỏi phải áp dụng các quy tắc ký cụ thể của nhà cung cấp, sử dụng khóa bí mật (secret key) hoặc khóa công khai (public key), kết hợp với các byte thô nguyên bản của phần thân yêu cầu (raw body bytes). Việc kiểm tra sự tồn tại của tiêu đề chữ ký không đồng nghĩa với việc chứng minh yêu cầu đó là hợp lệ hoặc an toàn.
Hướng dẫn sử dụng công cụ kiểm tra yêu cầu Webhook
Công cụ này cho phép bạn dán phương thức, tiêu đề và nội dung thô của một yêu cầu webhook đã chụp để phân tích cấu trúc và tạo lệnh kiểm tra cục bộ.
Các bước thực hiện:
- Chọn Phương thức: Chọn phương thức HTTP phù hợp từ danh sách (POST, PUT, PATCH, GET, DELETE).
- Nhập Tiêu đề: Dán các tiêu đề của yêu cầu vào ô Tiêu đề. Mỗi tiêu đề nằm trên một dòng riêng biệt theo định dạng chuẩn
Tên: giá trị. Giới hạn tối đa là 200 dòng tiêu đề không trống và tổng số ký tự không vượt quá 100.000. - Nhập Thân máy: Dán chính xác nội dung thô được chụp trước khi qua bất kỳ bộ phân tích cú pháp nào vào ô Thân máy. Giới hạn tối đa cho phần thân là 1.000.000 ký tự.
- Xem kết quả: Công cụ sẽ tự động phân tích và hiển thị thông tin chi tiết.
Kết quả đầu ra bao gồm:
- Nội dung được định dạng: Hiển thị cấu trúc trực quan của JSON hoặc dữ liệu biểu mẫu URL-encoded. Nếu không có dữ liệu, hệ thống hiển thị
(nội dung trống). - Trường chữ ký: Danh sách các tiêu đề chữ ký hoặc dấu thời gian được phát hiện. Nếu không tìm thấy, hệ thống hiển thị
Không tìm thấy chữ ký chung hoặc tiêu đề dấu thời gian webhook.. - Kiểm tra cURL cục bộ: Một lệnh cURL được định cấu hình sẵn để gửi yêu cầu đến địa chỉ kiểm tra cục bộ
http://localhost:3000/webhooks.
Các quy tắc xử lý và thông báo lỗi
Trong quá trình xử lý dữ liệu đầu vào, công cụ áp dụng các quy tắc nghiêm ngặt và có thể đưa ra các cảnh báo lỗi sau:
| Thông báo lỗi | Nguyên nhân |
|---|---|
Dán ít nhất một tiêu đề hoặc nội dung yêu cầu trước. |
Người dùng chưa nhập bất kỳ thông tin nào vào ô tiêu đề hoặc thân máy. |
Tiêu đề quá dài đối với công cụ này. Xóa các giá trị không liên quan hoặc lặp lại. |
Tổng số ký tự trong phần tiêu đề vượt quá giới hạn 100.000 ký tự. |
Phần thân quá dài đối với công cụ này. Giữ nó dưới 1.000.000 ký tự. |
Nội dung phần thân vượt quá giới hạn 1.000.000 ký tự. |
Có quá nhiều dòng tiêu đề. Giữ yêu cầu ở mức 200 tiêu đề hoặc ít hơn. |
Số lượng dòng tiêu đề vượt quá giới hạn 200 dòng. |
‹line›: Dòng tiêu đề không hợp lệ. Tên sử dụng: giá trị. |
Dòng tiêu đề thứ ‹line› không tuân thủ đúng định dạng phân tách bằng dấu hai chấm. |
Nội dung trông giống JSON nhưng không thể phân tích cú pháp. |
Phần thân có định dạng tương tự JSON nhưng chứa lỗi cú pháp khiến hàm JSON.parse không thể xử lý. |
Nội dung biểu mẫu chứa phần trăm thoát không đầy đủ. |
Dữ liệu dạng URL-encoded chứa chuỗi mã hóa phần trăm % không hợp lệ hoặc bị cắt cụt. |
Quyền riêng tư và xử lý dữ liệu
Mọi thao tác xử lý dữ liệu, phân tích cú pháp và định dạng yêu cầu webhook đều được thực hiện trực tiếp bên trong trình duyệt web của bạn. Yêu cầu đã dán của bạn vẫn ở trong trình duyệt của bạn. BroBroGo không tải lên hoặc lưu nó.
Câu hỏi thường gặp (FAQ)
Trang này có thể nhận lệnh gọi lại webhook trực tiếp không? Không. Dán yêu cầu đã chụp vào đây để kiểm tra. Trang không tạo điểm cuối công khai, không nhận lệnh gọi lại hoặc gửi yêu cầu kiểm tra đã tạo.
Tôi có thể kiểm tra những định dạng nội dung webhook nào? Nội dung biểu mẫu được mã hóa JSON và URL được phát hiện và định dạng. Các nội dung khác vẫn ở dạng văn bản thuần túy nên công cụ không đoán được nội dung XML, nhiều phần hoặc nhị phân.
Việc tìm thấy trường chữ ký có chứng minh được yêu cầu là xác thực không? Không. Công cụ này chỉ hiển thị các tiêu đề chữ ký và dấu thời gian liên quan. Việc xác minh thực sự cần có quy tắc ký chính xác của người gửi, khóa bí mật hoặc khóa chung và các byte yêu cầu ban đầu. Tìm thấy trường chữ ký không chứng minh được yêu cầu là hợp lệ — việc xác minh thực sự cần có quy tắc ký, khóa bí mật hoặc khóa của người gửi, và các byte yêu cầu gốc.