Webhooks

Webhook là một yêu cầu HTTP mà TicketWave gửi đến bạn. Bất cứ khi nào có điều gì đó xảy ra trên máy chủ của bạn — một ticket được mở, một thành viên bị đưa vào danh sách đen — TicketWave sẽ POST một body JSON đến một URL do bạn sở hữu.

Đó là điểm khác biệt so với Log Channels: log channels ghi một embed vào Discord để con người đọc, còn webhook chuyển sự kiện thô trực tiếp cho mã của bạn.

Tạo Endpoint

Yêu cầu đối với Endpoint

Yêu cầu HTTP

Mỗi lần gửi là một POST với body JSON.

Headers

Body

Mọi payload đều dùng cùng một khung bao. Chỉ data là khác nhau theo từng loại sự kiện:

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T08:23:11.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1042",
    "ticket_num_id": 1042,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "created_at": "2026-08-26T08:23:11.000Z"
  }
}

Xem Event Reference để biết đối tượng data của từng loại.

Xác minh chữ ký

Bất kỳ ai phát hiện ra URL endpoint của bạn đều có thể gửi một yêu cầu POST đến đó. Chữ ký là cách bạn phân biệt một lần gửi thật từ TicketWave với một yêu cầu giả mạo.

Chữ ký được tạo như thế nào

TicketWave ghép timestamp và body yêu cầu thô bằng dấu chấm, rồi chạy HMAC-SHA256 trên kết quả bằng secret của endpoint:

signed_payload = X-TicketWave-Timestamp + "." + raw_request_body
signature      = HMAC_SHA256(signed_payload, your_endpoint_secret)

Header sẽ mang digest đó dưới dạng hex và có tiền tố: sha256=<digest>.

Bộ nhận của bạn phải làm gì

Một triển khai hoàn chỉnh có ở trang Example Server.

Thử lại

Một lần gửi thất bại sẽ được tự động thử lại.

Các lần gửi không được sắp xếp theo thứ tự. Nếu hai ticket được tạo cùng lúc, các yêu cầu có thể đến theo bất kỳ thứ tự nào — hãy dùng trường timestamp trong body nếu thứ tự quan trọng với bạn.

Lịch sử gửi

Trang Webhooks trong dashboard liệt kê mọi lần gửi cùng trạng thái, mã phản hồi, thời lượng và số lần thử. Mở một dòng để xem chính xác payload đã được gửi và phản hồi mà server của bạn trả về.

Các lần gửi thất bại có thể được gửi lại từ trang chi tiết bằng Retry Webhook. Nó sẽ gửi lại payload gốc đến cùng endpoint và ghi nhận một lần gửi mới.

Khắc phục sự cố

Bước tiếp theo

• Event Reference (Mọi sự kiện và payload của nó)
• Example Server (Một bộ nhận Express có thể chạy được)
• Log Channels (Các sự kiện giống nhau, nhưng được đăng vào Discord)