Konfigurasikan Webhook

Published: 16 Juli 2026 · Last updated: 21 Juli 2026 · By Marcus Biel

Webhook memungkinkan Maildroppa memberi tahu aplikasi lain saat terjadi sesuatu yang penting di akun Anda.

Alih-alih berulang kali menanyakan kepada Maildroppa apakah subscriber telah dibuat, diperbarui, berhenti berlangganan, atau diberi tag, aplikasi Anda dapat menerima permintaan HTTPS segera setelah peristiwa terjadi.

Halaman Webhook adalah pusat integrasi di seluruh akun ini. Anda dapat membuat beberapa endpoint, memilih peristiwa yang diterima setiap endpoint, menambahkan header autentikasi, menguji koneksi, memeriksa percobaan pengiriman, dan mengirim ulang peristiwa produksi jika diperlukan.

Cara Kerja Webhook Akun

Webhook akun mengikuti proses berikut:

1. Sebuah peristiwa terjadi di Maildroppa, misalnya subscriber dibuat.
2. Maildroppa menemukan setiap endpoint aktif yang berlangganan peristiwa tersebut.
3. Maildroppa membuat satu pengiriman untuk setiap endpoint yang sesuai.
4. Payload JSON ditandatangani dengan Signing secret webhook akun Anda.
5. Maildroppa mengirim permintaan HTTPS POST ke URL endpoint yang tersimpan.
6. Endpoint Anda memverifikasi tanda tangan, menyimpan atau memproses peristiwa, lalu mengembalikan respons HTTP.
7. Maildroppa mencatat hasilnya dalam riwayat pengiriman dan secara otomatis mencoba kembali kegagalan sementara.

Jika beberapa endpoint berlangganan peristiwa yang sama, setiap endpoint menerima pengirimannya sendiri. Peristiwa bisnis memiliki Event ID yang sama untuk semuanya, sementara setiap pengiriman memiliki Delivery ID sendiri.

Webhook akun berbeda dari langkah “Send a webhook” di dalam Automation. Webhook akun memantau peristiwa akun yang dipilih di seluruh Maildroppa. Webhook Automation hanya dikirim saat subscriber mencapai langkah tertentu tersebut. Keduanya menggunakan Signing secret webhook akun, sehingga rotasi secret memengaruhi setiap penerima webhook keluar yang memverifikasi tanda tangan Maildroppa.

Membuka Halaman Webhook

Buka “Settings”, perluas “Developers”, lalu pilih “Webhooks”.

Halaman ini memiliki tiga area utama:

• Signing secret
• Endpoints
• Riwayat pengiriman untuk endpoint yang dipilih

Jika Anda memiliki lebih dari satu endpoint, pilih baris endpoint untuk menampilkan riwayat pengirimannya. Jika Anda belum memilih endpoint secara eksplisit, Maildroppa menampilkan riwayat endpoint pertama dalam daftar.

Sebelum Membuat Endpoint

Siapkan penerima di server Anda sebelum mengonfigurasi Maildroppa. Penerima tersebut harus:

• Tersedia melalui URL HTTPS publik.
• Menerima permintaan POST dengan body application/json.
• Mempertahankan body permintaan mentah sampai tanda tangan Maildroppa diverifikasi.
• Mengembalikan status 2xx hanya setelah peristiwa diterima dengan aman.
• Memproses pengiriman berulang secara idempoten menggunakan Event ID.
• Merespons dengan cepat, bukan melakukan pekerjaan lambat selama permintaan berlangsung.

Pola yang andal adalah memverifikasi permintaan, menyimpan Event ID dan payload dalam antrean atau database yang tahan lama, mengembalikan 200 atau 204, lalu memproses tindakan bisnis setelahnya.

Jangan mengekspos komputer pengembangan, alamat jaringan lokal, atau skrip yang tidak terlindungi sebagai penerima webhook produksi. Maildroppa hanya menerima target HTTPS publik dan memeriksa kembali tujuan saat pengiriman dilakukan.

Langkah 1: Buat Signing Secret

Setiap permintaan webhook Maildroppa ditandatangani. Penerima Anda menggunakan Signing secret untuk memverifikasi bahwa permintaan dibuat oleh Maildroppa dan body tidak diubah selama transmisi.

Di bagian atas halaman, panel Signing secret menampilkan salah satu status berikut:

• Missing — Belum ada Signing secret.
• Ready — Signing secret telah dikonfigurasi.
• Loading — Maildroppa sedang mengambil status saat ini.

Klik “Generate secret” saat statusnya Missing.

Maildroppa langsung menampilkan secret baru. Secret tersebut diawali dengan whsec_. Klik “Copy”, lalu simpan di pengelola secret atau konfigurasi lingkungan terlindungi yang digunakan penerima Anda.

Nilai lengkap hanya ditampilkan segera setelah pembuatan atau rotasi. Saat Anda memuat ulang atau meninggalkan halaman, Maildroppa hanya menampilkan bahwa secret tersedia dan kapan terakhir diperbarui. Secret yang tersimpan tidak ditampilkan kembali.

Jika Anda Kehilangan Secret

Jika penerima tidak lagi memiliki secret saat ini, klik “Rotate secret” dan simpan nilai yang baru ditampilkan.

Rotasi langsung menggantikan secret sebelumnya. Maildroppa tidak menyimpan kedua nilai selama masa transisi. Perbarui setiap penerima yang menggunakan secret akun ini sebelum mengirim pengujian berikutnya atau mengandalkan pengiriman produksi.

Pengiriman baru, percobaan ulang terjadwal, pengujian, dan pengiriman ulang ditandatangani dengan secret saat ini pada waktu permintaan HTTP dibuat. Artinya, pengiriman yang dibuat sebelum rotasi masih dapat ditandatangani dengan secret baru saat dicoba setelah rotasi.

Perlakukan Secret Seperti Kata Sandi

Jangan menempatkan Signing secret dalam kode browser, repositori publik, URL, halaman error, atau log aplikasi biasa.

Hanya penerima sisi server yang memerlukan secret tersebut. Jika Anda yakin secret telah terekspos, lakukan rotasi dan segera perbarui semua penerima.

Memverifikasi Tanda Tangan Webhook

Setiap permintaan berisi header Maildroppa berikut:

• X-Maildroppa-Event-Id — Mengidentifikasi peristiwa bisnis.
• X-Maildroppa-Delivery-Id — Mengidentifikasi pengiriman tertentu ini.
• X-Maildroppa-Timestamp — Waktu penandatanganan dalam detik Unix.
• X-Maildroppa-Signature — Tanda tangan HMAC berversi.

Maildroppa juga mengirim:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

Tanda tangan memiliki format berikut:

v1=<lowercase hexadecimal HMAC>

Maildroppa membuatnya dengan HMAC-SHA256. Konten yang ditandatangani adalah timestamp, diikuti titik, lalu body permintaan JSON mentah yang persis sama:

<timestamp>.<raw request body>

Gunakan Signing secret sebagai kunci HMAC.

Contoh Node.js berikut menunjukkan langkah penting verifikasi. rawBody harus berupa byte permintaan asli, bukan JSON yang sudah diurai lalu diserialisasi ulang.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Setelah memverifikasi tanda tangan, bandingkan juga timestamp dengan waktu server Anda. Tolak permintaan yang berada di luar toleransi singkat yang dipilih untuk infrastruktur Anda, misalnya lima menit. Ini mengurangi risiko permintaan valid yang tertangkap digunakan kembali jauh setelahnya.

Urai dan proses JSON hanya setelah kedua pemeriksaan berhasil.

Penyebab Umum Error Tanda Tangan

Tanda tangan biasanya gagal karena salah satu alasan berikut:

• Penerima menggunakan secret lama setelah rotasi.
• Middleware mengurai atau mengubah JSON sebelum tanda tangan dihitung.
• Penerima hanya menandatangani body dan menghilangkan <timestamp>..
• Timestamp diperlakukan sebagai tanggal berformat, bukan nilai header yang persis.
• Awalan v1= dihilangkan dari perbandingan.
• HMAC yang dihitung dikodekan dengan cara berbeda, bukan dalam heksadesimal huruf kecil.

Catat Event ID dan Delivery ID saat verifikasi gagal, tetapi jangan pernah mencatat Signing secret atau nilai custom header yang sensitif.

Langkah 2: Tambahkan Endpoint

Klik “Add endpoint” di bagian Endpoints.

Editor terdiri dari empat bagian:

• Endpoint URL
• Events
• Custom headers
• Active status

Endpoint baru dimulai sebagai Active, dan semua peristiwa yang ditampilkan di editor awalnya dipilih. Tinjau pilihan tersebut sebelum menyimpan agar penerima hanya mendapatkan notifikasi yang benar-benar dibutuhkan.

Mengonfigurasi Endpoint URL

Masukkan URL publik lengkap yang harus menerima permintaan Maildroppa, misalnya:

https://integrations.example.com/webhooks/maildroppa

URL harus memenuhi persyaratan berikut:

• Harus menggunakan https://.
• Harus berisi hostname publik yang valid.
• Panjangnya dapat mencapai 2.048 karakter.
• Tidak boleh berisi variabel template dengan { atau }.
• Tidak boleh berisi nama pengguna atau kata sandi sebelum hostname.
• Tidak boleh berisi fragmen URL yang diawali #.
• Harus menggunakan port HTTPS standar 443.
• Tidak boleh menggunakan localhost, alamat IP mentah, atau hostname yang mengarah ke jaringan privat atau jaringan yang dicadangkan dan diblokir.

Parameter kueri didukung, tetapi jangan menempatkan API key atau secret lain dalam URL. URL terlihat dalam daftar endpoint dan data pengiriman. Gunakan Custom header untuk kredensial.

Maildroppa tidak mengikuti pengalihan. Simpan tujuan HTTPS akhir, bukan URL yang mengembalikan 301, 302, 307, atau 308.

Hostname tujuan di-resolve kembali sebelum pengiriman. Hostname yang kemudian mengarah ke alamat privat atau diblokir akan ditolak meskipun valid saat endpoint disimpan.

Memilih Peristiwa

Pilih setidaknya satu peristiwa. Endpoint hanya menerima jenis peristiwa yang dipilih di editornya.

Halaman ini menawarkan pilihan peristiwa berikut:

Subscriber Created — subscriber.created

Dikirim saat subscriber dibuat di akun Maildroppa.

Gunakan peristiwa ini untuk membuat kontak terkait di CRM, platform data pelanggan, database internal, atau sistem lain yang memperhatikan izin.

Jangan menafsirkan peristiwa ini sebagai bukti bahwa setiap pendaftaran telah menyelesaikan Double Opt-in. Status subscriber dalam payload menjelaskan keadaan saat ini.

Subscriber Updated — subscriber.updated

Dikirim saat informasi subscriber bawaan atau nilai custom field berubah.

Gunakan objek subscriber lengkap dalam payload sebagai representasi Maildroppa saat ini. Hindari menganggap bahwa hanya satu properti tertentu yang berubah.

Penambahan dan penghapusan tag memiliki jenis peristiwa sendiri agar dapat ditangani secara terpisah.

Subscriber Unsubscribed — subscriber.unsubscribed

Dikirim saat subscriber berpindah ke status unsubscribed melalui tindakan berhenti berlangganan.

Gunakan peristiwa ini untuk menekan kontak di sistem yang terhubung. Jangan otomatis mendaftarkan kembali orang tersebut hanya karena sistem lain masih menandai kontak sebagai aktif.

Tag Added — subscriber.tag_added

Dikirim saat tag ditetapkan kepada subscriber.

Payload berisi subscriber dan tag yang terlibat dalam perubahan ini.

Tag Removed — subscriber.tag_removed

Dikirim saat tag dihapus dari subscriber.

Payload berisi subscriber yang diperbarui dan tag yang dihapus. Tag yang dihapus diberikan secara terpisah meskipun sudah tidak ada dalam array tags subscriber saat ini.

Form Submitted — form.submitted

Dikirim saat pengunjung mengirimkan formulir pendaftaran Maildroppa.

Perlakukan ini sebagai sinyal pengiriman formulir, bukan konfirmasi bahwa Double Opt-in telah selesai. Alur kerja apa pun yang memerlukan langganan terkonfirmasi harus tetap menghormati status subscriber saat ini dan proses konfirmasi.

Gunakan Endpoint Terpisah Saat Tanggung Jawab Berbeda

Anda dapat mengirim peristiwa berbeda ke sistem berbeda. Contohnya:

• Kirim peristiwa subscriber dan tag ke CRM.
• Kirim peristiwa berhenti berlangganan ke layanan suppression.
• Kirim peristiwa pengiriman formulir ke pipeline analitik.

Endpoint terpisah mengurangi lalu lintas yang tidak perlu dan memudahkan diagnosis kegagalan. Setiap endpoint memiliki pilihan peristiwa, URL, custom header, status aktif, pengujian, dan riwayat pengiriman sendiri.

Menambahkan Custom Header

Custom header bersifat opsional. Gunakan saat penerima memerlukan API key, bearer token, pengenal tenant, atau header tetap lainnya.

Klik “Add header”, lalu masukkan Header name dan Header value. Contoh yang sesuai meliputi:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Anda dapat menambahkan hingga 20 custom header.

Nama header:

• Wajib diisi.
• Dapat berisi hingga 128 karakter.
• Harus menggunakan karakter nama header HTTP yang valid.
• Harus unik tanpa membedakan huruf besar dan kecil.

Nilai header:

• Wajib diisi.
• Dapat berisi hingga 2.000 karakter.
• Tidak boleh berisi jeda baris.

Nama berikut dicadangkan dan tidak dapat digantikan oleh custom header:

• Content-Type
• Content-Length
• Host
• User-Agent
• Nama apa pun yang diawali X-Maildroppa-

Ini mencegah nilai khusus menggantikan header pengiriman dan tanda tangan Maildroppa.

Cara Penyimpanan Secret Header

Maildroppa mengenkripsi nilai custom header sebelum menyimpannya. Nilai yang tersimpan tidak dikembalikan ke browser dalam bentuk yang dapat dibaca.

Saat Anda mengedit endpoint nanti, kolom nilai menampilkan “Stored value kept”. Biarkan kosong jika secret yang ada harus tetap tidak berubah. Masukkan nilai baru untuk menggantinya.

Jika Anda mengubah nama header, masukkan kembali nilainya. Maildroppa hanya mempertahankan secret tersimpan selama nama header aslinya tidak berubah.

Menghapus baris header akan menghapus header tersebut dari pengiriman mendatang setelah endpoint disimpan.

Nilai custom header diperlakukan sebagai data sensitif dalam informasi permintaan tersimpan. Nilai tersebut disamarkan, bukan ditampilkan, dalam riwayat pengiriman.

Mengatur Endpoint Aktif atau Tidak Aktif

Biarkan “Active” dipilih saat endpoint siap menerima peristiwa segera.

Hapus pilihannya jika Anda ingin menyimpan konfigurasi tanpa memulai pengiriman. Anda dapat mengaktifkan endpoint nanti dari daftar endpoint.

Endpoint tidak aktif:

• Tidak menerima peristiwa baru yang terjadi.
• Tidak dapat mengirim Test webhook.
• Tetap terlihat dan dapat diedit.
• Tetap menyimpan riwayat pengiriman yang ada.

Mengaktifkan endpoint tidak mengisi kembali peristiwa yang terjadi saat endpoint tidak aktif.

Klik “Save” saat URL, pilihan peristiwa, header, dan status sudah benar.

Memahami Daftar Endpoint

Setiap baris endpoint menampilkan:

• URL tujuan.
• Lencana Active atau Inactive.
• Jenis peristiwa yang diikuti.
• Jumlah custom header.
• Waktu terakhir endpoint diperbarui.

Tindakan yang tersedia adalah:

• On/Off — Mengaktifkan atau menonaktifkan endpoint.
• Test — Mengirim satu permintaan pengujian segera ke endpoint aktif.
• Edit — Mengubah URL, peristiwa, header, atau status aktif.
• Delete — Menghapus konfigurasi endpoint secara permanen setelah konfirmasi.

Pilih bagian utama suatu baris untuk membuka riwayat pengiriman endpoint tersebut di bawah daftar.

Dampak Perubahan Tersimpan terhadap Pengiriman yang Ada

Peristiwa akun membuat pengiriman dengan snapshot URL endpoint, payload, dan custom header pada saat itu.

Mengedit URL atau custom header memengaruhi pengiriman yang baru dibuat. Pengiriman yang sudah berada dalam antrean mempertahankan tujuan dan konfigurasi header aslinya.

Mengubah peristiwa yang dipilih juga hanya memengaruhi peristiwa yang terjadi setelahnya. Maildroppa tidak membuat pengiriman secara retroaktif untuk jenis peristiwa yang tidak dipilih saat peristiwa terjadi.

Signing secret berbeda: secret dibaca saat permintaan HTTP disiapkan. Karena itu, pengiriman tertunda atau pengiriman ulang dapat menggunakan Signing secret yang baru dirotasi meskipun payload dan snapshot endpoint dibuat sebelumnya.

Menguji Endpoint

Klik “Test” pada endpoint aktif setelah penerima dan Signing secret siap.

Maildroppa segera mengirim satu permintaan bertanda tangan menggunakan URL endpoint dan custom header yang tersimpan. Perubahan yang belum disimpan dalam editor terbuka tidak termasuk dalam pengujian.

Payload pengujian menggunakan jenis peristiwa webhook.test dan menetapkan livemode ke false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

ID dan timestamp yang dibuat berbeda untuk setiap pengujian nyata.

Pengujian melakukan tepat satu percobaan HTTP. Pengiriman pengujian tidak ditempatkan dalam jadwal percobaan ulang produksi dan tidak dapat dikirim ulang.

Setelah permintaan selesai, panel hasil menampilkan:

• Test success atau Test failed
• Event ID
• Status HTTP, jika respons diterima
• Durasi
• Delivery ID
• Informasi error, jika tersedia
• Cuplikan respons, jika penerima mengembalikan body

Pengujian juga muncul dalam riwayat pengiriman dengan lencana Test. Gunakan filter “Test” untuk menampilkan hanya permintaan pengujian.

Memahami Payload Produksi

Peristiwa akun produksi menggunakan envelope JSON umum:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Properti tingkat atas berarti:

• id — Event ID. Nilainya cocok dengan X-Maildroppa-Event-Id.
• type — Kunci peristiwa yang dipilih dalam editor endpoint.
• schema_version — Versi skema payload. Gunakan saat menentukan cara mengurai peristiwa.
• created_at — Waktu payload peristiwa dibuat, dalam UTC.
• livemode — true untuk peristiwa produksi dan false untuk peristiwa pengujian.
• data — Konten khusus peristiwa.

Rutekan peristiwa berdasarkan nilai type yang tepat. Abaikan properti tambahan yang tidak diperlukan integrasi Anda agar penambahan payload yang kompatibel tidak merusak penerima.

Payload Peristiwa Subscriber

Peristiwa subscriber berisi representasi subscriber saat ini di dalam data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields dan tags adalah array. Keduanya dapat kosong. Properti subscriber juga dapat bernilai null jika tidak ada nilai, sehingga penerima Anda harus mengikuti skema payload, bukan menganggap setiap nilai profil opsional selalu tersedia.

Payload Peristiwa Tag

Peristiwa tag berisi subscriber dan tag yang menyebabkan peristiwa:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Untuk subscriber.tag_removed, data.tag tetap mengidentifikasi tag yang dihapus meskipun array tags subscriber saat ini tidak lagi memuatnya.

Event ID, Delivery ID, dan Idempotensi

Event ID dan Delivery ID memiliki tujuan berbeda.

Event ID

Event ID mengidentifikasi peristiwa bisnis. ID ini muncul di:

• Properti id tingkat atas pada payload.
• Header permintaan X-Maildroppa-Event-Id.
• Riwayat pengiriman.

Peristiwa yang sama dapat dikirim ke beberapa endpoint yang berlangganan. Pengiriman tersebut memiliki Event ID yang sama.

Percobaan ulang dan pengiriman ulang manual juga mempertahankan Event ID asli. Simpan Event ID yang telah diproses dan buat tindakan bisnis idempoten agar permintaan berulang tidak membuat kontak duplikat, mengulangi tindakan yang tidak dapat dibatalkan, atau menerapkan perubahan yang sama dua kali.

Delivery ID

Delivery ID mengidentifikasi satu catatan pengiriman. ID ini muncul di:

• Header permintaan X-Maildroppa-Delivery-Id.
• Riwayat pengiriman.

Setiap pengiriman endpoint memiliki Delivery ID sendiri. Pengiriman ulang manual membuat Delivery ID baru dengan tetap mempertahankan Event ID asli.

Gunakan Delivery ID untuk pelacakan teknis dan dukungan. Gunakan Event ID untuk deduplikasi tingkat bisnis.

Mengembalikan Respons HTTP yang Tepat

Maildroppa mengklasifikasikan respons sebagai berikut:

• Respons 2xx apa pun menandai pengiriman sebagai berhasil.
• Respons 408 Request Timeout, 429 Too Many Requests, dan 5xx adalah kegagalan sementara dan dapat dicoba kembali.
• Kegagalan jaringan yang mungkin bersifat sementara akan dicoba kembali.
• Pengalihan dan respons 3xx lainnya tidak diikuti dan diperlakukan sebagai kegagalan terminal.
• Respons 4xx lainnya diperlakukan sebagai kegagalan terminal dan tidak dicoba kembali.

Kembalikan 200, 202, atau 204 hanya jika peristiwa telah diterima dengan aman. Jika pemrosesan membutuhkan waktu, simpan peristiwa terlebih dahulu dan kembalikan respons berhasil sebelum melakukan pekerjaan yang lebih lambat secara asinkron.

Jangan mengembalikan pengalihan ke URL webhook lain. Konfigurasikan URL akhir di Maildroppa.

Jadwal Percobaan Ulang Otomatis

Pengiriman produksi dapat melakukan hingga tujuh percobaan HTTP.

Setelah kegagalan yang dapat dicoba kembali, Maildroppa menjadwalkan percobaan berikutnya dengan jeda berikut:

1. Setelah percobaan 1: 1 menit
2. Setelah percobaan 2: 5 menit
3. Setelah percobaan 3: 30 menit
4. Setelah percobaan 4: 2 jam
5. Setelah percobaan 5: 12 jam
6. Setelah percobaan 6: 24 jam

Jika percobaan 7 masih menerima kegagalan yang dapat dicoba kembali, pengiriman menjadi Dead dan tidak ada percobaan otomatis berikutnya yang dijadwalkan.

Jadwal dihitung dari setiap percobaan yang gagal. Waktu pengiriman aktual dapat sedikit lebih lambat karena pengiriman diproses secara asinkron dan juga tunduk pada batas perlindungan sistem.

Perbaiki masalah sementara pada penerima sebelum waktu “Next retry” yang ditampilkan jika memungkinkan. Jika percobaan otomatis telah berakhir, gunakan Replay setelah penerima kembali sehat.

Memahami Riwayat Pengiriman

Riwayat pengiriman merupakan milik endpoint yang sedang dipilih. URL endpoint muncul di header bagian sehingga Anda dapat memastikan riwayat yang sedang dilihat.

Gunakan filter berikut:

• All — Menampilkan pengiriman produksi dan pengujian.
• Production — Hanya menampilkan pengiriman peristiwa langsung.
• Test — Hanya menampilkan pengujian manual.

Klik “Refresh” untuk mengambil status terbaru. Riwayat tidak perlu dibiarkan terbuka saat Maildroppa mengirim atau mencoba kembali pengiriman.

Halaman menampilkan 50 pengiriman terbaru yang sesuai dengan filter yang dipilih.

Kolom Pengiriman

Setiap baris berisi:

• Created — Waktu catatan pengiriman dibuat.
• State — Pending, Success, Failed, atau Dead.
• HTTP — Status respons, jumlah percobaan, durasi, dan waktu percobaan berikutnya jika berlaku.
• Subscriber — Email subscriber saat peristiwa terkait dengan subscriber.
• Delivery — Jenis peristiwa, Event ID, dan Delivery ID.
• Actions — Replay jika pengiriman memenuhi syarat.

Jika tidak ada permintaan HTTP yang dilakukan, kolom HTTP menampilkan “No HTTP attempt”. Ini dapat terjadi ketika Maildroppa menolak permintaan sebelum mengirim, misalnya karena Signing secret tidak tersedia atau tujuan tersimpan tidak lagi dapat digunakan dengan aman.

Jika tersedia, baris tersebut juga menampilkan Error dan Response excerpt yang dikembalikan penerima. Jangan mengembalikan secret atau data pribadi sensitif dalam body respons webhook karena sebagian respons tersebut dapat muncul dalam log pengiriman akun.

Status Pengiriman

Pending berarti pengiriman sedang menunggu percobaan pertama atau percobaan ulang terjadwal. “Next retry” muncul saat percobaan lain telah dijadwalkan.

Success berarti penerima mengembalikan respons 2xx. Tidak diperlukan percobaan otomatis berikutnya.

Failed berarti pengiriman berakhir karena masalah yang tidak dapat dicoba kembali, ditolak sebelum percobaan HTTP, atau dihentikan sebelum dapat dikirim.

Dead berarti semua percobaan otomatis untuk masalah yang dapat dicoba kembali telah digunakan tanpa menerima respons berhasil.

Retensi Riwayat

Catatan pengiriman disimpan untuk waktu terbatas:

• Pengiriman produksi berhasil: 30 hari
• Pengiriman produksi gagal: 90 hari
• Pengiriman produksi Dead: 90 hari
• Pengiriman pengujian: 30 hari

Simpan log integrasi Anda sendiri jika memerlukan riwayat audit yang lebih panjang. Simpan Event ID dan Delivery ID, tetapi hindari menyimpan secret tanpa alasan yang diperlukan.

Mengirim Ulang Pengiriman

Klik “Replay” saat pengiriman produksi yang selesai perlu dicoba kembali.

Replay tersedia untuk pengiriman produksi dalam status Success, Failed, atau Dead. Fitur ini tidak tersedia saat pengiriman berstatus Pending, dan pengiriman pengujian tidak dapat dikirim ulang.

Pengiriman ulang:

• Membuat pengiriman Pending baru.
• Membuat Delivery ID baru.
• Mempertahankan Event ID asli.
• Mempertahankan jenis peristiwa dan payload JSON asli.
• Menggunakan URL target tersimpan asli dan snapshot custom header.
• Menggunakan Signing secret saat ini ketika permintaan baru disiapkan.

Replay tidak membuat ulang payload dari data subscriber saat ini. Fitur ini mengirim ulang snapshot peristiwa asli. Dengan demikian, pengiriman ulang dapat diaudit dan mencegah peristiwa historis berubah makna secara diam-diam.

Hanya satu pengiriman ulang dari pengiriman sumber yang sama yang dapat berstatus Pending pada satu waktu. Tunggu hingga pengiriman ulang tersebut selesai sebelum memintanya lagi.

Pastikan endpoint Active sebelum melakukan pengiriman ulang. Jika endpoint tidak aktif, pengiriman ulang yang diantrekan tidak dapat berhasil dikirim.

Karena penerima mungkin telah menyelesaikan tindakan bisnis meskipun Maildroppa tidak menerima respons berhasil, pengiriman ulang dapat menghasilkan permintaan duplikat. Deduplikasi Event ID melindungi sistem yang terhubung dari pengulangan tindakan.

Mengedit Endpoint

Klik “Edit” untuk mengubah URL, pilihan peristiwa, custom header, atau status aktif.

Sebelum menyimpan:

1. Pastikan URL baru sudah tersedia.
2. Biarkan nilai header tersimpan kosong jika harus tetap tidak berubah.
3. Masukkan nilai baru untuk setiap header yang namanya diubah.
4. Tinjau pilihan peristiwa agar notifikasi yang diperlukan tidak terhapus secara tidak sengaja.
5. Simpan dan kirim Test webhook baru.

Ingat bahwa pengiriman yang diantrekan mempertahankan URL dan snapshot custom header yang ada. Uji konfigurasi baru untuk pengiriman mendatang, bukan berasumsi bahwa konfigurasi tersebut mengubah permintaan lama yang masih diantrekan.

Menonaktifkan Endpoint

Gunakan tombol On/Off saat ingin menjeda integrasi tanpa menghapus konfigurasi dan riwayatnya.

Saat endpoint dimatikan:

• Peristiwa baru tidak lagi diantrekan untuk endpoint tersebut.
• Pengiriman Pending yang belum diambil untuk dikirim ditandai Failed.
• Test dinonaktifkan.
• Endpoint tetap tersedia untuk diedit dan diaktifkan kembali nanti.

Permintaan yang sudah berlangsung saat penonaktifan masih dapat selesai. Periksa riwayat pengiriman setelah mematikan endpoint jika perbedaan ini penting bagi integrasi Anda.

Peristiwa yang terlewat saat endpoint tidak aktif tidak akan diisi kembali saat Anda mengaktifkannya lagi.

Menghapus Endpoint

Klik “Delete” dan konfirmasikan peringatan saat endpoint tidak boleh ada lagi.

Penghapusan menghapus endpoint dari halaman, menghentikan pengiriman peristiwa mendatang, dan menggagalkan pengiriman Pending yang belum diambil untuk dikirim.

Delete bukan cara untuk menjeda sementara. Gunakan tombol On/Off jika Anda mungkin memerlukan konfigurasi atau riwayat yang terlihat lagi.

Sebelum menghapus, catat Event ID atau Delivery ID yang masih diperlukan untuk audit integrasi Anda.

Pemecahan Masalah

Endpoint Tidak Dapat Disimpan

Periksa bahwa:

• URL diawali dengan https://.
• URL menggunakan hostname publik dan port 443.
• URL tidak berisi variabel, informasi login, atau fragmen.
• Setidaknya satu peristiwa dipilih.
• Setiap Custom header memiliki nama unik dan nilai.
• Header Maildroppa dan HTTP yang dicadangkan tidak digunakan sebagai nama khusus.

Test Dinonaktifkan

Test hanya tersedia untuk endpoint Active. Nyalakan endpoint atau edit endpoint dan pilih “Active”, lalu simpan sebelum melakukan pengujian.

Test Menampilkan Tidak Ada Percobaan HTTP

Buat Signing secret jika statusnya Missing. Periksa juga apakah hostname tujuan bersifat publik dan masih di-resolve dengan benar.

Permintaan dapat ditolak sebelum dikirim jika secret, URL, custom header, atau pemeriksaan keamanan tujuan tidak valid.

Penerima Mengembalikan 401 atau 403

Periksa nama Custom header dan kredensial yang tersimpan. Edit endpoint dan masukkan kembali nilainya jika telah berubah.

Pastikan juga penerima tidak keliru membedakan kredensial API miliknya sendiri dengan tanda tangan Maildroppa. Custom authorization header dan X-Maildroppa-Signature memiliki tujuan berbeda dan dapat diperiksa secara terpisah.

Penerima Mengembalikan Pengalihan

Maildroppa tidak mengikuti pengalihan. Ganti URL endpoint dengan URL HTTPS publik akhir, lalu uji kembali.

Tanda Tangan Tidak Cocok

Pastikan penerima:

• Menggunakan Signing secret saat ini.
• Menggunakan nilai X-Maildroppa-Timestamp yang persis.
• Menandatangani <timestamp>.<raw request body>.
• Menggunakan HMAC-SHA256 dan output heksadesimal huruf kecil.
• Membandingkan nilai lengkap termasuk v1=.
• Melakukan perbandingan sebelum penguraian JSON mengubah body.

Peristiwa yang Sama Tiba Lebih dari Sekali

Ini dapat terjadi setelah gangguan jaringan, percobaan ulang, atau pengiriman ulang manual. Sistem pengiriman webhook umumnya menyediakan pengiriman setidaknya satu kali, bukan pengiriman tepat satu kali.

Gunakan Event ID sebagai kunci idempotensi. Kembalikan respons 2xx saat Event ID yang sudah diproses diterima lagi dan tidak diperlukan tindakan tambahan.

Pengiriman Berstatus Pending

Lihat “Next retry” di kolom HTTP. 408, 429, 5xx, atau kegagalan jaringan sementara yang dapat dicoba kembali akan tetap berstatus Pending sampai percobaan terjadwal berikutnya.

Klik “Refresh” setelah waktu percobaan ulang untuk memuat status terbaru.

Pengiriman Berstatus Dead

Semua percobaan otomatis telah digunakan. Perbaiki penerima terlebih dahulu, pastikan endpoint Active, kirim Test webhook, lalu gunakan Replay pada pengiriman produksi.

Checklist Produksi yang Disarankan

Sebelum mengandalkan endpoint dalam produksi, pastikan semua hal berikut:

1. Penerima menggunakan URL HTTPS publik yang stabil dengan sertifikat valid.
2. Signing secret disimpan di luar kode sumber.
3. Tanda tangan diperiksa terhadap body mentah yang tidak diubah.
4. Timestamp lama ditolak sesuai toleransi yang terdokumentasi.
5. Penerima menyimpan dan mendeduplikasi Event ID.
6. Penerima mencatat Event ID dan Delivery ID untuk pelacakan.
7. Pemrosesan lambat dilakukan setelah peristiwa diterima secara persisten.
8. Respons 2xx hanya dikembalikan untuk peristiwa yang diterima.
9. Kredensial khusus disimpan dalam header, bukan URL.
10. Hanya jenis peristiwa yang diperlukan yang dipilih.
11. Test webhook berhasil dan muncul dengan benar dalam riwayat pengiriman.
12. Pemantauan memberi tahu Anda saat pengiriman produksi mulai mengembalikan error.

Dengan perlindungan ini, halaman Webhook menyediakan kedua sisi integrasi yang andal: pengiriman peristiwa yang aman ke aplikasi Anda dan riwayat operasional yang jelas di dalam Maildroppa.