Tài liệu nhà phát triển

Mã nguồn tạo Raw Body lập trình

Dùng các hàm này để đảm bảo chuỗi JSON tạo ra luôn là chuỗi Minified (không khoảng trắng thừa), khớp với cơ chế ký của Gateway.

// Dùng Newtonsoft.Json với Formatting.None
var rawBody = JsonConvert.SerializeObject(yourModel, Formatting.None);

// Dùng json_encode (mặc định là minified)
$rawBody = json_encode($yourArray, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

// Dùng Jackson ObjectMapper
ObjectMapper mapper = new ObjectMapper();
String rawBody = mapper.writeValueAsString(yourModel); // Mặc định là minified

// Dùng JSON.stringify không kèm tham số indent
const rawBody = JSON.stringify(yourModel);

Tại sao Webhook báo lỗi hoặc sai Chữ ký?

Nếu bạn nhận được Webhook nhưng không thể gạch nợ thành công, hãy kiểm tra 2 vấn đề sau:

Best Practice: Bền vững hóa API Webhook

Để tránh việc hệ thống bị lỗi (HTTP 400/500) mỗi khi Gateway cập nhật hoặc bổ sung trường dữ liệu mới, đối tác cần tuân thủ nguyên tắc thiết kế sau:

• KHÔNG dùng Class/Model cố định để nhận tham số trực tiếp tại hàm Webhook.
• KHÔNG chặn các trường dữ liệu lạ (Unknown properties).
• CHỈ nên quan tâm đến các trường cốt lõi bạn cần dùng cho logic gạch nợ.

Cấu trúc API Webhook khuyên dùng (C#):

// Thiết kế API "Mở" - Không sợ thay đổi tham số
[HttpPost]
public async Task<IHttpActionResult> ReceiveWebhook() 
{
    // 1. Nhận chuỗi thô (Luôn luôn thành công)
    string rawBody = await Request.Content.ReadAsStringAsync();
    
    // 2. Lấy chữ ký X-Signature từ Header để xác thực (Tùy framework)
    // - Với ASP.NET Web API:
    Request.Headers.TryGetValues("X-Signature", out IEnumerable<string> values);
    string signature = values?.FirstOrDefault() ?? "";
    
    // - Với ASP.NET Core: 
    // string signature = Request.Headers["X-Signature"].FirstOrDefault();
    
    // 3. Parse linh hoạt vào Dictionary
    var data = JsonConvert.DeserializeObject<Dictionary<string, object>>(rawBody);
    
    // 4. Lấy dữ liệu cần thiết
    string orderCode = data.ContainsKey("order_code") ? data["order_code"].ToString() : "";
    string status = data.ContainsKey("status") ? data["status"].ToString() : "";
    
    // ... Kiểm tra chữ ký và gạch nợ ...
    return Ok();
}