Webhook

Usher có thể báo cho máy chủ của bạn những gì xảy ra trong một môi trường ngay khi chúng xảy ra: ai đó tham gia, đăng nhập, thay đổi thông tin hoặc rời đi. Mỗi sự kiện là một yêu cầu POST có chữ ký đến địa chỉ bạn chọn, được gửi lại nếu máy chủ của bạn không phản hồi.

Thêm endpoint

Trong Usher Console, mở môi trường, rồi chọn Webhook → Endpoint mới. Nhập một địa chỉ https:// của bạn và chọn các sự kiện mà endpoint cần nhận. Console hiển thị mã bí mật ký của endpoint (whsec_…) một lần: hãy giữ nó cùng các thông tin bí mật khác của máy chủ.

Gửi thử gửi một sự kiện webhook.test chỉ đến endpoint đó, bất kể endpoint đã đăng ký nhận sự kiện nào.

Những gì được gửi đến

POST /usher/webhooks HTTP/1.1
content-type: application/json
user-agent: Usher-Webhooks/1
webhook-id: msg_2fk7x…
webhook-timestamp: 1793643116
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

{
  "type": "user.created",
  "timestamp": "2026-11-02T18:11:56.412Z",
  "data": {
    "user": {
      "id": "Qz3m…",
      "email": "lena@acme.com",
      "emailVerified": false,
      "name": "Lena Live",
      "image": null,
      "banned": false,
      "createdAt": "2026-11-02T18:11:56.380Z",
      "updatedAt": "2026-11-02T18:11:56.380Z"
    }
  }
}

Sự kiện mô tả người dùng và phiên, không bao giờ mô tả thông tin bí mật: không có token, không có giá trị băm của mật khẩu, không có vai trò, và không có lý do ai đó bị cấm.

Kiểm tra mọi lần gửi

Usher ký theo đặc tả Standard Webhooks, nên bất kỳ thư viện nào của đặc tả này cũng kiểm tra chữ ký giúp bạn. Hãy từ chối mọi thứ không xác minh được. Các thư viện cũng từ chối dấu thời gian lệch quá năm phút, nên không thể phát lại một lần gửi cũ.

// a route that receives Usher's webhooks (Node, the standardwebhooks package)
import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.USHER_WEBHOOK_SECRET!) // whsec_…, from Usher Console

export async function POST(request: Request) {
  const body = await request.text() // the raw body: the signature covers it byte for byte
  let event: { type: string; timestamp: string; data: Record<string, unknown> }
  try {
    event = wh.verify(body, Object.fromEntries(request.headers)) as typeof event
  } catch {
    return new Response('bad signature', { status: 400 })
  }
  // webhook-id is the same on every attempt: skip one you have handled already
  if (await alreadyHandled(request.headers.get('webhook-id')!)) return new Response(null, { status: 204 })
  await queue(event) // answer quickly; do the work afterwards
  return new Response(null, { status: 204 })
}

• Phản hồi trong vòng 15 giây bằng bất kỳ mã 2xx nào. Mọi phản hồi khác, kể cả chuyển hướng, đều bị tính là thất bại.
• Chờ đợi sự lặp lại. Một thông điệp giữ nguyên webhook-id ở mọi lần thử; hãy bỏ qua thông điệp bạn đã xử lý.
• Đừng dựa vào thứ tự. Các lần gửi lại có thể đến sau những sự kiện mới hơn.

Khi máy chủ của bạn không phản hồi

Usher thử lại sau 5 giây, 5 phút, 30 phút, 2 giờ, 5 giờ, 10 giờ và 10 giờ (tổng cộng khoảng một ngày rưỡi), rồi dừng. Nhật ký gửi trong Console hiển thị mọi lần thử của từng thông điệp và phản hồi gần nhất của máy chủ bạn, và Gửi lại sẽ bắt đầu lại một lần gửi.

Mã bí mật mới

Mã bí mật mới trong Console tạo thêm một mã khác và hiển thị nó một lần. Trong 24 giờ tiếp theo, mỗi lần gửi mang hai chữ ký, mỗi mã bí mật một chữ ký, để bạn có thể triển khai mã bí mật mới mà không bỏ lỡ gì. Sau đó, chỉ mã mới được dùng để ký.

Các lần gửi đến từ đâu

Webhook rời khỏi Usher qua proxy đi ra của nó, vốn không kết nối đến các địa chỉ riêng tư hoặc nội bộ. Endpoint phải là một địa chỉ https:// trên một tên công khai: không phải địa chỉ IP, tên riêng tư, hay một địa chỉ trên các tên miền của chính Usher.