Sinyal andal untuk pekerjaan yang membutuhkan waktu

Daftarkan endpoint

Tambahkan endpoint di halaman Pengembang, atau dengan cakupan webhooks:write:

curl -s -X POST "$BASE/workspaces/$WS/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/mini-casa","events":["job.updated","publication.updated"]}'

Respons memuat signing_secret (whsec_...) yang hanya ditampilkan sekali. URL wajib menggunakan HTTPS pada port 443 dan hanya mengarah ke alamat publik; tujuan pribadi, loopback, serta internal ditolak, pemeriksaan diulang sebelum setiap pengiriman, dan pengalihan tidak pernah diikuti. Satu ruang kerja dapat memiliki hingga 10 endpoint aktif.

Buktikan bahwa Anda mengendalikannya

Endpoint baru dimulai dengan status pending_verification. Tombol Verifikasi (atau POST /webhooks/{id}/verify) mengirim satu webhook.challenge bertanda tangan. Jawab 2xx dengan {"challenge": "<data.challenge>"}, lalu endpoint menjadi active.

Peristiwa

• job.updated: pekerjaan atau proses massal berubah status.
• job.item.updated: satu item proses massal berubah status.
• domain.updated: domain kustom melewati pemeriksaannya.
• publication.updated: pembangunan dimulai, berhasil, gagal, atau digantikan.
• approval.updated: persetujuan diputuskan, kedaluwarsa, atau digunakan.
• billing.entitlement.updated: paket atau hak akses berubah.

Isi hanya memuat id serta status, tidak pernah kredensial, konten, atau data pribadi. Ambil status saat ini melalui API.

Verifikasi setiap permintaan

Setiap permintaan memiliki SmallWorld-Webhook-Id, SmallWorld-Webhook-Timestamp (detik unix), dan SmallWorld-Webhook-Signature (v1=<hex>,kid=<key id>). Tanda tangan adalah HMAC-SHA256 dari <timestamp>.<raw body> menggunakan rahasia Anda. Gunakan isi mentah sebelum penguraian JSON apa pun, bandingkan dalam waktu konstan, dan tolak stempel waktu yang berbeda lebih dari lima menit dari jam Anda.

import crypto from "node:crypto";

export function verify(secret, timestamp, rawBody, header) {
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const given = /v1=([a-f0-9]+)/.exec(header)?.[1] ?? "";
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  return fresh && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Jaminan pengiriman

• Setidaknya sekali. Permintaan diulang hingga Anda menjawab 2xx. Id peristiwa tetap sama pada setiap percobaan ulang dan pengiriman ulang, jadi simpan id dan abaikan yang sudah pernah Anda lihat.
• Jeda percobaan ulang bertambah dari satu menit hingga satu hari, selama total 72 jam. Setelah itu, pengiriman menjadi pesan gagal permanen yang dapat dikirim kembali dari halaman Pengembang atau melalui redeliver_webhook.
• Endpoint dengan 10 peristiwa gagal permanen berturut-turut dijeda hingga Anda melanjutkannya.
• Urutan tidak dijamin: perlakukan status sebagai petunjuk dan baca sumber dayanya.