Webhook

Usher dapat memberi tahu server Anda apa yang terjadi di sebuah lingkungan saat itu juga: seseorang bergabung, masuk, mengubah detailnya, atau pergi. Setiap peristiwa adalah POST bertanda tangan ke alamat pilihan Anda, yang dicoba lagi jika server Anda tidak menjawab.

Tambahkan endpoint

Di Usher Console, buka lingkungan, lalu Webhook → Endpoint baru. Masukkan alamat https:// milik Anda dan pilih peristiwa yang perlu diberitahukan kepadanya. Console menampilkan rahasia penandatanganan endpoint (whsec_…) satu kali: simpan bersama rahasia lain di server Anda.

Kirim uji coba mengirim peristiwa webhook.test hanya ke endpoint itu, apa pun langganannya.

Yang diterima

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 menggambarkan orang dan sesi, tidak pernah rahasia: tanpa token, tanpa hash kata sandi, tanpa peran, dan tanpa alasan seseorang diblokir.

Periksa setiap pengiriman

Usher menandatangani sesuai spesifikasi Standard Webhooks, sehingga pustaka mana pun dari spesifikasi itu memeriksa tanda tangannya untuk Anda. Tolak apa pun yang gagal diverifikasi. Pustaka-pustaka itu juga menolak stempel waktu yang selisihnya lebih dari lima menit, sehingga pengiriman lama tidak dapat diputar ulang.

// 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 15 detik dengan 2xx apa pun. Jawaban lain, termasuk pengalihan, dihitung sebagai kegagalan.
• Bersiaplah menerima pengulangan. Sebuah pesan mempertahankan webhook-id yang sama di setiap percobaan; lewati pesan yang sudah Anda tangani.
• Jangan mengandalkan urutan. Percobaan ulang bisa tiba setelah peristiwa yang lebih baru.

Saat server Anda tidak menjawab

Usher mencoba lagi 5 detik, 5 menit, 30 menit, 2 jam, 5 jam, 10 jam, dan 10 jam kemudian (total sekitar satu setengah hari), lalu berhenti. Log pengiriman di Console menampilkan setiap percobaan pesan dan jawaban terakhir server Anda, dan Kirim lagi memulai pengiriman dari awal.

Rahasia baru

Rahasia baru di Console membuat rahasia lain dan menampilkannya sekali. Selama 24 jam berikutnya, setiap pengiriman membawa dua tanda tangan, satu per rahasia, sehingga Anda dapat memasang rahasia baru tanpa melewatkan apa pun. Setelah itu hanya rahasia baru yang menandatangani.

Asal pengiriman

Webhook keluar dari Usher melalui proxy egress-nya, yang tidak akan terhubung ke alamat privat atau internal. Endpoint harus berupa alamat https:// pada nama publik: bukan alamat IP, nama privat, atau alamat di domain milik Usher sendiri.