Webhook

Usher boleh memberitahu pelayan anda apa yang berlaku dalam sesebuah persekitaran sebaik sahaja ia berlaku: seseorang menyertai, daftar masuk, menukar butirannya atau pergi. Setiap peristiwa ialah POST bertandatangan ke alamat yang anda pilih, dicuba semula jika pelayan anda tidak menjawab.

Tambah titik akhir

Dalam Usher Console, buka persekitaran, kemudian Webhook → Titik akhir baharu. Berikan alamat https:// milik anda dan pilih peristiwa yang patut diketahuinya. Console menunjukkan rahsia tandatangan titik akhir itu (whsec_…) sekali sahaja: simpan bersama rahsia lain pelayan anda.

Hantar ujian menghantar peristiwa webhook.test kepada titik akhir itu sahaja, apa pun yang dilanggannya.

Apa yang tiba

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"
    }
  }
}

Peristiwa menerangkan orang dan sesi, tidak sekali-kali rahsia: tiada token, tiada cincangan kata laluan, tiada peranan, dan tiada sebab seseorang disekat.

Semak setiap penghantaran

Usher menandatangani mengikut spesifikasi Standard Webhooks, jadi mana-mana pustakanya menyemak tandatangan untuk anda. Tolak apa sahaja yang tidak dapat disahkan. Pustaka itu juga menolak cap masa yang berbeza lebih daripada lima minit, jadi penghantaran lama tidak boleh dimainkan semula.

// 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 })
}

• Jawab dalam masa 15 saat dengan mana-mana 2xx. Selain itu, termasuk ubah hala, dikira sebagai kegagalan.
• Jangka ulangan. Mesej mengekalkan webhook-id pada setiap cubaan; langkau mesej yang telah anda kendalikan.
• Jangan bergantung pada susunan. Cubaan semula boleh tiba selepas peristiwa yang lebih baharu.

Apabila pelayan anda tidak menjawab

Usher mencuba lagi 5 saat, 5 minit, 30 minit, 2 jam, 5 jam, 10 jam dan 10 jam kemudian (kira-kira satu setengah hari keseluruhannya), kemudian berhenti. Log penghantaran Console menunjukkan setiap cubaan mesej dan jawapan terakhir pelayan anda, dan Hantar semula memulakan semula penghantaran.

Rahsia baharu

Rahsia baharu dalam Console membuat rahsia lain dan menunjukkannya sekali. Selama 24 jam berikutnya, setiap penghantaran membawa dua tandatangan, satu bagi setiap rahsia, supaya anda boleh menggunakan rahsia baharu tanpa terlepas apa-apa. Selepas itu, hanya rahsia baharu yang menandatangan.

Dari mana penghantaran datang

Webhook keluar dari Usher melalui proksi keluarnya, yang tidak akan menyambung ke alamat peribadi atau dalaman. Titik akhir mestilah alamat https:// pada nama awam: bukan alamat IP, nama peribadi, atau alamat di domain Usher sendiri.