Вебхуктар

Usher ортада не болып жатқанын серверлеріңізге сол сәтте хабарлай алады: біреу қосылады, кіреді, деректерін өзгертеді немесе кетеді. Әр оқиға — сіз таңдаған мекенжайға жіберілетін қол қойылған POST сұрауы, серверіңіз жауап бермесе, ол қайта жіберіледі.

Соңғы нүкте қосыңыз

Usher Console ішінде ортаны ашып, Вебхуктар → Жаңа соңғы нүкте тармағын таңдаңыз. Өзіңіздің https:// мекенжайыңызды беріп, ол қандай оқиғалар туралы білуі керек екенін таңдаңыз. Console соңғы нүктенің қолтаңба құпиясын (whsec_…) бір рет көрсетеді: оны серверіңіздің басқа құпияларымен бірге сақтаңыз.

Сынақ жіберу қандай оқиғаларға жазылғанына қарамастан, тек сол соңғы нүктеге webhook.test оқиғасын жібереді.

Не келеді

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

Оқиғалар құпияларды емес, адамдар мен сеанстарды сипаттайды: токендер жоқ, құпиясөз хэштері жоқ, рөлдер жоқ және біреудің неге бұғатталғаны да жоқ.

Әр жеткізілімді тексеріңіз

Usher Standard Webhooks спецификациясы бойынша қол қояды, сондықтан оның кез келген кітапханасы қолтаңбаны сіз үшін тексереді. Тексеруден өтпегеннің бәрін қабылдамаңыз. Кітапханалар бес минуттан астам алшақ уақыт белгісін де қабылдамайды, сондықтан ескі жеткізілімді қайта ойнату мүмкін емес.

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

• 15 секунд ішінде кез келген 2xx кодымен жауап беріңіз. Қалғанының бәрі, қайта бағыттауды қоса, сәтсіздік болып саналады.
• Қайталануды күтіңіз. Хабар әр әрекетте өзінің webhook-id мәнін сақтайды; өңдеп қойғаныңызды өткізіп жіберіңіз.
• Ретке сенбеңіз. Қайталау әрекеттері жаңа оқиғалардан кейін келуі мүмкін.

Серверіңіз жауап бермегенде

Usher 5 секундтан, 5 минуттан, 30 минуттан, 2 сағаттан, 5 сағаттан, 10 сағаттан және тағы 10 сағаттан кейін қайта әрекет етеді (барлығы шамамен бір жарым тәулік), содан кейін тоқтайды. Console жеткізу журналында әр хабардың әрекеттері мен серверіңіздің соңғы жауабы көрсетіледі, ал Қайта жіберу жеткізуді басынан бастайды.

Жаңа құпия

Console ішіндегі Жаңа құпия басқа құпия жасап, оны бір рет көрсетеді. Келесі 24 сағат ішінде әр жеткізілімде әр құпияға бір-бірден екі қолтаңба болады, сондықтан жаңа құпияны ештеңені жіберіп алмай орната аласыз. Одан кейін тек жаңасы қол қояды.

Жеткізілімдер қайдан келеді

Вебхуктар Usher-ден оның шығыс проксиі арқылы шығады, ол жеке немесе ішкі мекенжайларға қосылмайды. Соңғы нүкте жария атауы бар https:// мекенжайы болуы керек: IP мекенжайы, жеке атау немесе Usher-дің өз домендеріндегі мекенжай емес.