Ditinjau 2026-11-11 · Versi API 2026-11-09 · Baca Markdown
Webhook pelanggan
Pengiriman peristiwa keluar untuk ruang kerja Anda. Daftarkan endpoint HTTPS, verifikasi rahasia penandatanganan sekali pakai, dan terima peristiwa bertanda tangan dengan percobaan ulang berbatas.
Mendaftarkan endpoint
curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
$BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
- Rahasia penandatanganan (
whsec_…) hanya dikembalikan satu kali: pada respons pembuatan sukses pertama. Simpan; pemutaran ulang idempoten dari pembuatan yang sama mengembalikan endpoint tanpa rahasia, dan ia tidak dapat ditampilkan lagi. - Tujuan harus HTTPS, dapat diresolusi secara publik, dan bebas dari kredensial tertanam. Permintaan ke alamat privat, loopback, link-local (termasuk metadata cloud), unique-local dan multicast ditolak sebelum koneksi apa pun dibuat, dan pengalihan tidak pernah diikuti.
- Pendaftaran memasukkan peristiwa
webhook.verificationtertarget untuk endpoint tersebut, independen dari filtereventTypes-nya. Peristiwa biasa hanya mengalir setelah endpoint Anda menjawab verifikasi dengan 2xx.
Memverifikasi pengiriman
Setiap permintaan membawa:
| Header | Makna |
|---|---|
x-publisher-event-id | ID peristiwa stabil: identik di seluruh percobaan ulang dan pemutaran ulang |
x-publisher-event-type | Jenis peristiwa, mis. post.published |
x-publisher-timestamp | Detik Unix |
x-publisher-signature | t=<ts>,v1=<hex> |
Tanda tangan adalah HMAC-SHA256 atas ${t}.${event_id}.${raw_body} menggunakan
rahasia penandatanganan Anda. Verifikasi dengan toleransi ±300 detik dan tolak pemutaran ulang
di luar rentang itu. Contoh Node:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, headers, rawBody) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
if (!m) return false;
const [t, v1] = [Number(m[1]), m[2]];
if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
.digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
Selalu verifikasi terhadap isi permintaan mentah sebelum mengurai.
Amplop peristiwa
{
"id": "0192d0d0-0000-7000-8000-00000000000f",
"type": "post.published",
"createdAt": "2026-11-09T12:00:01Z",
"apiVersion": "2026-11-09",
"data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}
Katalog peristiwa awal (dapat diperluas; eventTypes memfilter saat pendaftaran):
webhook.verification: muatan tantangan; jawab 2xx untuk mengaktifkan endpointpost.published: satu tujuan dikonfirmasi dengan tanda terima aslidelivery.failed: satu tujuan gagal secara finaldelivery.requires_action: perlu persetujuan/sambung ulang/peninjauan tertunda
Hasil agregat posting (post.partially_published, post.failed) belum
dipancarkan; mereka hanya didokumentasikan di sini setelah ada produsennya, jadi jangan
bergantung padanya. Berlangganan peristiwa per tujuan di atas dan turunkan status
batch dari hasil pengiriman posting.
Percobaan ulang, pemutaran ulang, dan penonaktifan
- Percobaan: segera, lalu +1m, +5m, +30m, +2h, +8h. Percobaan ulang menggunakan kembali ID peristiwa yang sama dan isi yang identik secara byte sehingga Anda dapat mendeduplikasi dengan aman.
- 2xx = terkirim. 429/5xx/timeout dicoba ulang. 4xx lainnya gagal permanen untuk peristiwa tersebut (perbaiki endpoint, lalu putar ulang).
- 410 Gone menonaktifkan endpoint: tidak ada peristiwa lain yang dimasukkan ke antreannya.
- Pemutaran ulang yang diizinkan operator melalui layanan webhook internal mengirim ulang peristiwa dengan ID aslinya. Percobaan yang sedang berjalan dengan sewa aktif tidak pernah dicabut; pemutaran ulang melaporkan bahwa peristiwa sedang sibuk dan dapat dicoba ulang segera.
Catatan operasional
- Diagnostik pengiriman hanya menyimpan kode hasil yang aman: bukan rahasia Anda, tanda tangan, header permintaan, atau isi respons. Muatan juga disanitasi: rahasia penyedia/OAuth dan URL presign media dihapus sebelum apa pun dimasukkan ke antrean.
- Endpoint berada dalam cakupan ruang kerja: kepemilikan UUID endpoint dari ruang kerja lain tidak berpengaruh.
- Pengiriman minimal sekali per kemunculan peristiwa yang diterima; deduplikasikan pada
x-publisher-event-id.
Ketersediaan alat pengembang
Halaman Developers mencantumkan kunci API ruang kerja dan endpoint webhook secara independen dari konfigurasi enkripsi rahasia penandatanganan. Pembuatan webhook memerlukan konfigurasi enkripsi server yang valid; minta operator deployment menyelesaikan peringatan konfigurasi. Manajemen kunci API tetap tersedia. Rahasia penandatanganan yang sudah ada tidak pernah ditampilkan lagi.