Apa itu webhook?

Saat Bird memanggil endpoint Anda, penerima harus menyimpan event sebelum pemrosesan dimulai. Webhook adalah permintaan HTTP yang dikirim satu sistem ke aplikasi Anda saat sesuatu terjadi. Pengirim menandatangani POST ke URL terdaftar Anda. Penerima Anda yang menentukan kapan event diterima secara tahan lama.

Apa perbedaan webhook dengan polling API?

Polling berarti aplikasi Anda memanggil API secara terjadwal dan memeriksa perubahan. Webhook membalik arah tersebut: penyedia memanggil endpoint Anda saat event terjadi, sehingga Anda menghindari permintaan yang sia-sia dan merespons lebih cepat.

Webhook memerlukan endpoint HTTPS publik yang dapat menerima permintaan selama event dikirim. Polling berfungsi dari mana saja dan memungkinkan aplikasi Anda memilih kapan mengambil state. Gunakan webhook untuk notifikasi yang tepat waktu. Gunakan API untuk mengambil detail resource lebih lengkap saat event hanya membawa identifier.

Seperti apa bentuk permintaan webhook?

Permintaan webhook adalah HTTP POST dengan header dan envelope event JSON. Event pengiriman email Bird memiliki type, timestamp event, dan data khusus tipe:

{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

ID pesan adalah data.email_id. Identitas pengiriman adalah header webhook-id, yang tetap sama saat Bird mencoba ulang atau memutar ulang event tersebut. timestamp pada body mencatat kapan event terjadi. Header webhook-timestamp mencatat percobaan pengiriman ini, sehingga kedua timestamp menjawab pertanyaan yang berbeda. Lihat field event email untuk payload khusus event.

Bagaimana cara memverifikasi tanda tangan webhook?

Simpan byte permintaan mentah dan verifikasi tanda tangan sebelum mem-parse atau menyimpan event. SDK milik Bird memeriksa header webhook-id, webhook-timestamp, dan webhook-signature. Library ini menerapkan toleransi timestamp untuk Anda. Gunakan panduan tanda tangan alih-alih menulis verifier kedua.

Jika Anda perlu memahami input penandatanganan, Bird menggunakan {webhook-id}.{webhook-timestamp}.{raw request body}. Secret endpoint diawali dengan whsec_; hapus prefix tersebut dan base64-decode sisanya sebelum menghitung HMAC-SHA256. Selama rotasi secret, header tanda tangan dapat berisi beberapa nilai v1, yang dipisahkan spasi, jadi terima nilai yang cocok dari secret yang aktif.

Tolak permintaan yang salah format, tidak terautentikasi, atau kedaluwarsa sebelum disimpan. Mem-parse JSON terlebih dahulu dapat mengubah whitespace atau urutan key dan membuat byte tidak lagi cocok dengan pesan yang ditandatangani.

Bagaimana cara menyimpan dan mengonfirmasi webhook?

Simpan event yang sudah diverifikasi beserta pekerjaan tahan lamanya sebelum mengembalikan respons sukses. Masukkan event dengan key webhook-id. Masukkan item pekerjaan untuk event baru. Commit keduanya dalam satu transaksi atau desain inbox dan outbox tahan lama yang setara.

read raw bytes and headers
verify the signature and timestamp with the Bird SDK
begin a durable transaction
  insert the inbox event keyed by webhook-id, unless it already exists
  insert a durable work item for a new event
commit the transaction
return 204
worker processes the persisted event idempotently

Duplikat yang sudah tersimpan secara tahan lama dapat menerima 204 tanpa membuat pekerjaan tambahan. Kembalikan non-2xx saat commit tahan lama gagal, agar Bird mencoba ulang pengiriman. Setelah Anda mengembalikan respons sukses, coba ulang worker lokal dari catatan tahan lama Anda alih-alih mengharapkan Bird mengirim event lagi.

Urutan ini adalah desain aplikasi untuk semantik pengiriman at-least-once milik Bird. Ini bukan antrian yang dijalankan Bird untuk Anda. Panduan duplikat dan idempotensi membahas keputusan deduplikasi secara lebih mendetail.

Bagaimana cara kerja retry dan replay webhook?

Bird memberi pengiriman normal 15 detik untuk menerima respons. Status 2xx apa pun dianggap berhasil. Status non-2xx, redirect, atau timeout dianggap gagal dan mengikuti jadwal retry.

Kurva ini memiliki 8 percobaan termasuk permintaan awal. Setiap delay diterapkan plus atau minus 20% jitter. 429 atau timeout koneksi menaikkan delay dasar menjadi 60 detik. Nilai Retry-After positif dibatasi antara delay dasar dan dua kali delay dasar sebelum jitter, sehingga tabel menunjukkan delay dasar, bukan waktu kedatangan pasti. Lihat cara webhook gagal dicoba ulang untuk jalur kegagalan.

Pengiriman tidak berurutan, jadi jangan perbarui state aplikasi saat ini hanya berdasarkan urutan kedatangan. Gunakan timestamp event dan state resource Anda saat event dapat tiba tidak berurutan.

Saat pengiriman terlewat, periksa percobaan webhook. Perbaiki penerima. Buat replay webhook. Bird melewati pengiriman yang sudah berhasil diterima endpoint. Replay menggunakan kembali webhook-id asli, sehingga kunci dedupe yang sama melindunginya.

Apa yang harus Anda hubungkan setelah mempelajari dasar-dasar webhook?

Buat endpoint. Verifikasi dan terima secara tahan lama pengiriman bertanda tangannya. Periksa percobaan pengiriman. Putar ulang event yang terlewat. Kemudian gunakan rotasi secret untuk menerapkan signing secret baru tanpa kehilangan pengiriman.