Konfigurasikan Webhook

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

Webhook membolehkan Maildroppa memberitahu aplikasi lain apabila sesuatu yang penting berlaku dalam akaun anda.

Daripada bertanya berulang kali kepada Maildroppa sama ada seorang pelanggan telah dicipta, dikemas kini, berhenti melanggan atau diberikan tag, aplikasi anda boleh menerima permintaan HTTPS tidak lama selepas peristiwa itu berlaku.

Halaman Webhook ialah tempat utama untuk integrasi seluruh akaun ini. Anda boleh mencipta beberapa titik akhir, memilih peristiwa yang diterima oleh setiap titik akhir, menambah pengepala pengesahan, menguji sambungan, memeriksa percubaan penghantaran dan memainkan semula peristiwa pengeluaran apabila perlu.

Cara Webhook Akaun Berfungsi

Webhook akaun mengikuti proses ini:

1. Satu peristiwa berlaku dalam Maildroppa, seperti pelanggan dicipta.
2. Maildroppa mencari setiap titik akhir aktif yang melanggan peristiwa tersebut.
3. Maildroppa mencipta satu penghantaran untuk setiap titik akhir yang sepadan.
4. Muatan JSON ditandatangani dengan rahsia Signing webhook akaun anda.
5. Maildroppa menghantar permintaan POST HTTPS ke URL titik akhir yang disimpan.
6. Titik akhir anda mengesahkan tandatangan, menyimpan atau memproses peristiwa dan mengembalikan respons HTTP.
7. Maildroppa merekodkan hasilnya dalam sejarah penghantaran dan mencuba semula kegagalan sementara secara automatik.

Jika beberapa titik akhir melanggan peristiwa yang sama, setiap titik akhir menerima penghantaran sendiri. Peristiwa perniagaan mempunyai Event ID yang sama untuk semuanya, manakala setiap penghantaran mempunyai Delivery ID tersendiri.

Webhook akaun berbeza daripada langkah “Send a webhook” di dalam Automation. Webhook akaun mendengar peristiwa akaun terpilih di seluruh Maildroppa. Webhook Automation dihantar hanya apabila pelanggan mencapai langkah tertentu itu. Kedua-duanya menggunakan rahsia Signing webhook akaun, jadi penggiliran rahsia menjejaskan setiap penerima webhook keluar yang mengesahkan tandatangan Maildroppa.

Membuka Halaman Webhook

Buka “Settings”, kembangkan “Developers” dan pilih “Webhooks”.

Halaman ini mengandungi tiga bahagian utama:

• Signing secret
• Endpoints
• Sejarah penghantaran untuk titik akhir yang dipilih

Apabila anda mempunyai lebih daripada satu titik akhir, pilih baris titik akhir untuk memaparkan sejarah penghantarannya. Jika anda belum memilih satu secara jelas, Maildroppa memaparkan sejarah titik akhir pertama dalam senarai.

Sebelum Mencipta Titik Akhir

Sediakan penerima pada pelayan anda sebelum mengkonfigurasi Maildroppa. Penerima hendaklah:

• Boleh dicapai melalui URL HTTPS awam.
• Menerima permintaan POST dengan isi application/json.
• Mengekalkan isi permintaan mentah sehingga tandatangan Maildroppa disahkan.
• Mengembalikan status 2xx hanya selepas peristiwa diterima dengan selamat.
• Memproses penghantaran berulang secara idempoten menggunakan Event ID.
• Memberi respons dengan cepat dan tidak melakukan kerja lambat semasa permintaan berlangsung.

Corak yang boleh dipercayai ialah mengesahkan permintaan, menyimpan Event ID dan muatan dalam baris gilir atau pangkalan data tahan lama, mengembalikan 200 atau 204, kemudian memproses tindakan perniagaan selepas itu.

Jangan dedahkan komputer pembangunan, alamat rangkaian tempatan atau skrip yang tidak dilindungi sebagai penerima webhook pengeluaran. Maildroppa hanya menerima sasaran HTTPS awam dan memeriksa destinasi sekali lagi apabila penghantaran dibuat.

Langkah 1: Jana Signing Secret

Setiap permintaan webhook Maildroppa ditandatangani. Penerima anda menggunakan Signing secret untuk mengesahkan bahawa permintaan itu dicipta oleh Maildroppa dan isi permintaan tidak diubah semasa penghantaran.

Di bahagian atas halaman, panel Signing secret memaparkan salah satu keadaan berikut:

• Missing — Tiada Signing secret wujud lagi.
• Ready — Signing secret telah dikonfigurasikan.
• Loading — Maildroppa sedang mendapatkan status semasa.

Klik “Generate secret” apabila status ialah Missing.

Maildroppa memaparkan rahsia baharu dengan serta-merta. Ia bermula dengan whsec_. Klik “Copy” dan simpannya dalam pengurus rahsia atau konfigurasi persekitaran terlindung yang digunakan oleh penerima anda.

Nilai lengkap hanya dipaparkan sejurus selepas penjanaan atau penggiliran. Apabila anda memuat semula atau meninggalkan halaman, Maildroppa hanya menunjukkan bahawa rahsia wujud dan bila kali terakhir ia dikemas kini. Maildroppa tidak mendedahkan semula rahsia yang disimpan.

Jika Anda Kehilangan Rahsia

Jika penerima tidak lagi mempunyai rahsia semasa, klik “Rotate secret” dan simpan nilai yang baharu dipaparkan.

Penggiliran menggantikan rahsia sebelumnya dengan serta-merta. Maildroppa tidak menyimpan kedua-dua nilai untuk tempoh peralihan. Kemas kini setiap penerima yang menggunakan rahsia akaun ini sebelum menghantar ujian lanjut atau bergantung pada penghantaran pengeluaran.

Penghantaran baharu, percubaan semula berjadual, ujian dan main semula ditandatangani dengan rahsia semasa pada waktu permintaan HTTP dibuat. Ini bermakna penghantaran yang dicipta sebelum penggiliran masih boleh ditandatangani dengan rahsia baharu apabila dicuba selepas itu.

Anggap Rahsia Seperti Kata Laluan

Jangan letakkan Signing secret dalam kod pelayar, repositori awam, URL, halaman ralat atau log aplikasi biasa.

Hanya penerima sebelah pelayan memerlukan rahsia tersebut. Jika anda percaya rahsia itu telah terdedah, putarkannya dan kemas kini semua penerima dengan segera.

Mengesahkan Tandatangan Webhook

Setiap permintaan mengandungi pengepala Maildroppa ini:

• X-Maildroppa-Event-Id — Mengenal pasti peristiwa perniagaan.
• X-Maildroppa-Delivery-Id — Mengenal pasti penghantaran tertentu ini.
• X-Maildroppa-Timestamp — Masa tandatangan dalam saat Unix.
• X-Maildroppa-Signature — Tandatangan HMAC berversi.

Maildroppa turut menghantar:

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

Tandatangan mempunyai format ini:

v1=<lowercase hexadecimal HMAC>

Maildroppa menciptanya menggunakan HMAC-SHA256. Kandungan yang ditandatangani ialah cap masa, diikuti noktah, kemudian isi permintaan JSON mentah yang tepat:

<timestamp>.<raw request body>

Gunakan Signing secret sebagai kunci HMAC.

Contoh Node.js berikut menunjukkan langkah pengesahan asas. rawBody mestilah bait permintaan asal, bukan JSON yang telah dihuraikan dan disiri semula.

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

Selepas mengesahkan tandatangan, bandingkan juga cap masa dengan masa pelayan anda. Tolak permintaan di luar toleransi singkat yang dipilih untuk infrastruktur anda, seperti lima minit. Ini mengurangkan risiko permintaan sah yang dirakam dimainkan semula jauh kemudian.

Hanya huraikan dan proses JSON selepas kedua-dua pemeriksaan berjaya.

Punca Biasa Ralat Tandatangan

Tandatangan biasanya gagal atas salah satu sebab berikut:

• Penerima menggunakan rahsia lama selepas penggiliran.
• Middleware menghuraikan atau mengubah JSON sebelum tandatangan dikira.
• Penerima hanya menandatangani isi dan meninggalkan <timestamp>..
• Cap masa dianggap sebagai tarikh berformat dan bukannya nilai pengepala yang tepat.
• Awalan v1= ditinggalkan daripada perbandingan.
• HMAC yang dikira dikodkan secara berbeza dan bukannya heksadesimal huruf kecil.

Logkan Event ID dan Delivery ID apabila pengesahan gagal, tetapi jangan sekali-kali logkan Signing secret atau nilai pengepala tersuai yang sensitif.

Langkah 2: Tambah Titik Akhir

Klik “Add endpoint” dalam bahagian Endpoints.

Editor mengandungi empat bahagian:

• Endpoint URL
• Events
• Custom headers
• Status aktif

Titik akhir baharu bermula sebagai Active dan semua peristiwa yang ditunjukkan dalam editor dipilih pada awalnya. Semak pilihan tersebut sebelum menyimpan supaya penerima hanya mendapat pemberitahuan yang benar-benar diperlukan.

Mengkonfigurasi URL Titik Akhir

Masukkan URL awam lengkap yang sepatutnya menerima permintaan Maildroppa, contohnya:

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

URL mestilah memenuhi keperluan berikut:

• Mesti menggunakan https://.
• Mesti mengandungi nama hos awam yang sah.
• Panjangnya boleh sehingga 2,048 aksara.
• Tidak boleh mengandungi pemboleh ubah templat dengan { atau }.
• Tidak boleh mengandungi nama pengguna atau kata laluan sebelum nama hos.
• Tidak boleh mengandungi fragmen URL yang bermula dengan #.
• Mesti menggunakan port HTTPS standard 443.
• Tidak boleh menggunakan localhost, alamat IP mentah atau nama hos yang diselesaikan kepada rangkaian peribadi atau terpelihara yang disekat.

Parameter pertanyaan disokong, tetapi jangan letakkan kunci API atau rahsia lain dalam URL. URL boleh dilihat dalam senarai titik akhir dan data penghantaran. Gunakan Custom header untuk kelayakan sebaliknya.

Maildroppa tidak mengikuti pengalihan. Simpan destinasi HTTPS akhir dan bukannya URL yang mengembalikan 301, 302, 307 atau 308.

Nama hos destinasi diselesaikan semula sebelum penghantaran. Nama hos yang kemudiannya diselesaikan kepada alamat peribadi atau disekat akan ditolak walaupun ia sah ketika titik akhir disimpan.

Memilih Peristiwa

Pilih sekurang-kurangnya satu peristiwa. Titik akhir hanya menerima jenis peristiwa yang dipilih dalam editornya.

Halaman ini menawarkan pilihan peristiwa berikut:

Subscriber Created — subscriber.created

Dihantar apabila pelanggan dicipta dalam akaun Maildroppa.

Gunakan peristiwa ini untuk mencipta kenalan yang sepadan dalam CRM, platform data pelanggan, pangkalan data dalaman atau sistem lain yang peka terhadap kebenaran.

Jangan tafsirkan peristiwa ini sebagai bukti bahawa setiap pendaftaran telah melengkapkan Double Opt-in. Status pelanggan dalam muatan menerangkan keadaan semasa.

Subscriber Updated — subscriber.updated

Dihantar apabila maklumat pelanggan terbina dalam atau nilai medan tersuai berubah.

Gunakan objek pelanggan lengkap dalam muatan sebagai gambaran semasa Maildroppa. Elakkan menganggap bahawa hanya satu sifat tertentu telah berubah.

Penetapan dan pengalihan tag mempunyai jenis peristiwa tersendiri supaya dapat dikendalikan secara berasingan.

Subscriber Unsubscribed — subscriber.unsubscribed

Dihantar apabila pelanggan beralih kepada status berhenti melanggan melalui tindakan berhenti melanggan.

Gunakan peristiwa ini untuk menyekat kenalan dalam sistem yang disambungkan. Jangan langgan semula orang itu secara automatik hanya kerana sistem lain masih menandakan kenalan tersebut sebagai aktif.

Tag Added — subscriber.tag_added

Dihantar apabila tag diberikan kepada pelanggan.

Muatan mengandungi pelanggan dan tag yang terlibat dalam perubahan khusus ini.

Tag Removed — subscriber.tag_removed

Dihantar apabila tag dialih keluar daripada pelanggan.

Muatan mengandungi pelanggan yang dikemas kini dan tag yang dialih keluar. Tag yang dialih keluar diberikan secara berasingan walaupun ia tidak lagi terdapat dalam tatasusunan tags semasa pelanggan.

Form Submitted — form.submitted

Dihantar apabila pelawat menghantar borang pendaftaran Maildroppa.

Anggap ini sebagai isyarat penghantaran borang, bukan pengesahan bahawa Double Opt-in telah dilengkapkan. Sebarang aliran kerja yang memerlukan langganan disahkan mesti terus menghormati status semasa pelanggan dan proses pengesahan.

Gunakan Titik Akhir Berasingan Apabila Tanggungjawab Berbeza

Anda boleh menghantar peristiwa berbeza kepada sistem berbeza. Contohnya:

• Hantar peristiwa pelanggan dan tag kepada CRM.
• Hantar peristiwa berhenti melanggan kepada perkhidmatan penindasan.
• Hantar peristiwa penghantaran borang kepada saluran analitik.

Titik akhir berasingan mengurangkan trafik yang tidak diperlukan dan memudahkan diagnosis kegagalan. Setiap titik akhir mempunyai pilihan peristiwa, URL, pengepala tersuai, status aktif, ujian dan sejarah penghantaran sendiri.

Menambah Pengepala Tersuai

Pengepala tersuai adalah pilihan. Gunakannya apabila penerima memerlukan kunci API, token pembawa, pengecam penyewa atau pengepala tetap lain.

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

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Anda boleh menambah sehingga 20 pengepala tersuai.

Nama pengepala:

• Diperlukan.
• Boleh mengandungi sehingga 128 aksara.
• Mesti menggunakan aksara nama pengepala HTTP yang sah.
• Mesti unik tanpa mengira huruf besar atau kecil.

Nilai pengepala:

• Diperlukan.
• Boleh mengandungi sehingga 2,000 aksara.
• Tidak boleh mengandungi pemisah baris.

Nama berikut dikhaskan dan tidak boleh digantikan oleh pengepala tersuai:

• Content-Type
• Content-Length
• Host
• User-Agent
• Mana-mana nama yang bermula dengan X-Maildroppa-

Ini menghalang nilai tersuai daripada menggantikan pengepala penghantaran dan tandatangan Maildroppa.

Cara Rahsia Pengepala Disimpan

Maildroppa menyulitkan nilai pengepala tersuai sebelum menyimpannya. Nilai yang disimpan tidak dikembalikan kepada pelayar dalam bentuk yang boleh dibaca.

Apabila anda mengedit titik akhir kemudian, medan nilai memaparkan “Stored value kept”. Biarkan kosong apabila rahsia sedia ada perlu dikekalkan. Masukkan nilai baharu untuk menggantikannya.

Jika anda menukar nama pengepala, masukkan nilai itu sekali lagi. Maildroppa mengekalkan rahsia yang disimpan hanya selagi nama pengepala asal tidak berubah.

Mengalih keluar baris pengepala akan mengalih keluar pengepala tersebut daripada penghantaran akan datang selepas titik akhir disimpan.

Nilai pengepala tersuai dianggap sensitif dalam maklumat permintaan yang disimpan. Nilai tersebut ditopeng dan bukannya dipaparkan dalam sejarah penghantaran.

Menetapkan Titik Akhir Aktif atau Tidak Aktif

Biarkan “Active” dipilih apabila titik akhir bersedia menerima peristiwa dengan serta-merta.

Nyahpilihnya apabila anda mahu menyimpan konfigurasi tanpa memulakan penghantaran. Anda boleh mengaktifkan titik akhir kemudian daripada senarai titik akhir.

Titik akhir tidak aktif:

• Tidak menerima peristiwa baharu yang berlaku.
• Tidak boleh menghantar Test webhook.
• Kekal kelihatan dan boleh diedit.
• Mengekalkan sejarah penghantaran sedia ada untuk diakses.

Mengaktifkan titik akhir tidak mengisi semula peristiwa yang berlaku ketika ia tidak aktif.

Klik “Save” apabila URL, pilihan peristiwa, pengepala dan status adalah betul.

Memahami Senarai Titik Akhir

Setiap baris titik akhir menunjukkan:

• URL destinasi.
• Lencana Active atau Inactive.
• Jenis peristiwa yang dilanggan.
• Bilangan pengepala tersuai.
• Masa titik akhir kali terakhir dikemas kini.

Tindakan yang tersedia ialah:

• On/Off — Mengaktifkan atau menyahaktifkan titik akhir.
• Test — Menghantar satu permintaan ujian segera kepada titik akhir aktif.
• Edit — Menukar URL, peristiwa, pengepala atau status aktif.
• Delete — Mengalih keluar konfigurasi titik akhir secara kekal selepas pengesahan.

Pilih bahagian utama baris untuk membuka sejarah penghantaran titik akhir tersebut di bawah senarai.

Kesan Perubahan yang Disimpan terhadap Penghantaran Sedia Ada

Peristiwa akaun mencipta penghantaran dengan petikan URL titik akhir, muatan dan pengepala tersuai pada masa tersebut.

Mengedit URL atau pengepala tersuai hanya menjejaskan penghantaran yang baru dicipta. Penghantaran yang telah berada dalam baris gilir mengekalkan destinasi asal dan konfigurasi pengepala yang disimpan.

Menukar peristiwa yang dipilih juga hanya menjejaskan peristiwa yang berlaku selepas itu. Maildroppa tidak mencipta penghantaran secara retrospektif untuk jenis peristiwa yang tidak dipilih ketika peristiwa berlaku.

Signing secret berbeza: ia dibaca apabila permintaan HTTP disediakan. Oleh itu, penghantaran yang menunggu atau main semula boleh menggunakan Signing secret yang baru diputar walaupun muatan dan petikan titik akhirnya dicipta lebih awal.

Menguji Titik Akhir

Klik “Test” pada titik akhir aktif selepas penerima dan Signing secret bersedia.

Maildroppa segera menghantar satu permintaan ditandatangani menggunakan URL titik akhir dan pengepala tersuai yang disimpan. Perubahan yang belum disimpan dalam editor terbuka tidak termasuk dalam ujian.

Muatan ujian menggunakan jenis peristiwa webhook.test dan menetapkan livemode kepada 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 cap masa yang dijana berbeza untuk setiap ujian sebenar.

Ujian membuat tepat satu percubaan HTTP. Penghantaran ujian tidak diletakkan dalam jadual percubaan semula pengeluaran dan tidak boleh dimainkan semula.

Selepas permintaan selesai, panel hasil menunjukkan:

• Test success atau Test failed
• Event ID
• Status HTTP, apabila respons diterima
• Tempoh
• Delivery ID
• Maklumat ralat, jika tersedia
• Petikan respons, apabila penerima mengembalikan isi

Ujian turut muncul dalam sejarah penghantaran dengan lencana Test. Gunakan penapis “Test” untuk memaparkan permintaan ujian sahaja.

Memahami Muatan Pengeluaran

Peristiwa akaun pengeluaran menggunakan sampul JSON biasa:

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

Sifat peringkat teratas bermaksud:

• id — Event ID. Ia sepadan dengan X-Maildroppa-Event-Id.
• type — Kunci peristiwa yang dipilih dalam editor titik akhir.
• schema_version — Versi skema muatan. Gunakannya apabila menentukan cara menghuraikan peristiwa.
• created_at — Masa muatan peristiwa dicipta, dalam UTC.
• livemode — true untuk peristiwa pengeluaran dan false untuk peristiwa ujian.
• data — Kandungan khusus peristiwa.

Halakan peristiwa mengikut nilai type yang tepat. Abaikan sifat tambahan yang tidak diperlukan oleh integrasi anda supaya penambahan muatan yang serasi tidak merosakkan penerima.

Muatan Peristiwa Pelanggan

Peristiwa pelanggan mengandungi perwakilan semasa pelanggan 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 ialah tatasusunan. Kedua-duanya boleh kosong. Sifat pelanggan juga boleh menjadi null apabila tiada nilai wujud, jadi penerima anda hendaklah mengikuti skema muatan dan bukannya menganggap setiap nilai profil pilihan sentiasa ada.

Muatan Peristiwa Tag

Peristiwa tag mengandungi pelanggan 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 masih mengenal pasti tag yang dialih keluar walaupun tatasusunan tags semasa pelanggan tidak lagi mengandunginya.

Event ID, Delivery ID dan Idempotensi

Event ID dan Delivery ID mempunyai tujuan yang berbeza.

Event ID

Event ID mengenal pasti peristiwa perniagaan. Ia muncul dalam:

• Sifat id peringkat teratas muatan.
• Pengepala permintaan X-Maildroppa-Event-Id.
• Sejarah penghantaran.

Peristiwa yang sama boleh dihantar kepada beberapa titik akhir yang dilanggan. Penghantaran tersebut berkongsi Event ID.

Percubaan semula dan main semula manual juga mengekalkan Event ID asal. Simpan Event ID yang telah diproses dan jadikan tindakan perniagaan idempoten supaya permintaan berulang tidak mencipta kenalan pendua, mengulangi tindakan yang tidak boleh dibuat asal atau menggunakan perubahan yang sama dua kali.

Delivery ID

Delivery ID mengenal pasti satu rekod penghantaran. Ia muncul dalam:

• Pengepala permintaan X-Maildroppa-Delivery-Id.
• Sejarah penghantaran.

Setiap penghantaran titik akhir mempunyai Delivery ID tersendiri. Main semula manual mencipta Delivery ID baharu sambil mengekalkan Event ID asal.

Gunakan Delivery ID untuk penjejakan teknikal dan sokongan. Gunakan Event ID untuk deduplikasi peringkat perniagaan.

Mengembalikan Respons HTTP yang Betul

Maildroppa mengelaskan respons seperti berikut:

• Sebarang respons 2xx menandakan penghantaran berjaya.
• Respons 408 Request Timeout, 429 Too Many Requests dan 5xx ialah kegagalan sementara dan boleh dicuba semula.
• Kegagalan rangkaian yang mungkin sementara akan dicuba semula.
• Pengalihan dan respons 3xx lain tidak diikuti dan dianggap kegagalan terminal.
• Respons 4xx lain dianggap kegagalan terminal dan tidak akan dicuba semula.

Kembalikan 200, 202 atau 204 hanya apabila peristiwa telah diterima dengan selamat. Jika pemprosesan mengambil masa, simpan peristiwa terlebih dahulu dan kembalikan respons berjaya sebelum melakukan kerja yang lebih lambat secara tak segerak.

Jangan kembalikan pengalihan ke URL webhook lain. Konfigurasikan URL akhir dalam Maildroppa.

Jadual Percubaan Semula Automatik

Penghantaran pengeluaran boleh membuat sehingga tujuh percubaan HTTP.

Selepas kegagalan yang boleh dicuba semula, Maildroppa menjadualkan percubaan seterusnya dengan kelewatan berikut:

1. Selepas percubaan 1: 1 minit
2. Selepas percubaan 2: 5 minit
3. Selepas percubaan 3: 30 minit
4. Selepas percubaan 4: 2 jam
5. Selepas percubaan 5: 12 jam
6. Selepas percubaan 6: 24 jam

Jika percubaan 7 masih menerima kegagalan yang boleh dicuba semula, penghantaran menjadi Dead dan tiada percubaan automatik seterusnya dijadualkan.

Jadual diukur daripada percubaan gagal individu. Masa penghantaran sebenar mungkin sedikit lewat kerana penghantaran diproses secara tak segerak dan turut tertakluk kepada had perlindungan sistem.

Baiki masalah sementara pada penerima sebelum masa “Next retry” yang dipaparkan jika boleh. Jika percubaan automatik telah tamat, gunakan Replay selepas penerima kembali sihat.

Memahami Sejarah Penghantaran

Sejarah penghantaran adalah milik titik akhir yang sedang dipilih. URL titik akhir muncul dalam pengepala bahagian supaya anda boleh mengesahkan sejarah yang sedang dilihat.

Gunakan penapis berikut:

• All — Menunjukkan penghantaran pengeluaran dan ujian.
• Production — Menunjukkan penghantaran peristiwa langsung sahaja.
• Test — Menunjukkan ujian manual sahaja.

Klik “Refresh” untuk mendapatkan keadaan terkini. Sejarah tidak perlu dibiarkan terbuka semasa Maildroppa menghantar atau mencuba semula penghantaran.

Halaman ini menunjukkan 50 penghantaran sepadan terkini untuk penapis yang dipilih.

Lajur Penghantaran

Setiap baris mengandungi:

• Created — Bila rekod penghantaran dicipta.
• State — Pending, Success, Failed atau Dead.
• HTTP — Status respons, bilangan percubaan dan tempoh, serta masa percubaan semula seterusnya apabila berkenaan.
• Subscriber — E-mel pelanggan apabila peristiwa berkaitan dengan pelanggan.
• Delivery — Jenis peristiwa, Event ID dan Delivery ID.
• Actions — Replay apabila penghantaran layak.

Jika tiada permintaan HTTP dibuat, lajur HTTP menunjukkan “No HTTP attempt”. Ini boleh berlaku apabila Maildroppa menolak permintaan sebelum menghantar, contohnya kerana Signing secret tiada atau destinasi yang disimpan tidak lagi boleh digunakan dengan selamat.

Jika tersedia, baris turut menunjukkan Error dan Response excerpt yang dikembalikan oleh penerima. Jangan kembalikan rahsia atau data peribadi sensitif dalam isi respons webhook kerana sebahagian daripada respons itu mungkin muncul dalam log penghantaran akaun.

Status Penghantaran

Pending bermaksud penghantaran sedang menunggu percubaan pertama atau percubaan semula berjadual. “Next retry” muncul apabila percubaan lain telah dijadualkan.

Success bermaksud penerima mengembalikan respons 2xx. Tiada percubaan automatik lanjut diperlukan.

Failed bermaksud penghantaran berakhir dengan masalah yang tidak boleh dicuba semula, ditolak sebelum percubaan HTTP atau dihentikan sebelum boleh dihantar.

Dead bermaksud semua percubaan automatik untuk masalah yang boleh dicuba semula telah digunakan tanpa menerima respons berjaya.

Pengekalan Sejarah

Rekod penghantaran disimpan untuk tempoh terhad:

• Penghantaran pengeluaran berjaya: 30 hari
• Penghantaran pengeluaran gagal: 90 hari
• Penghantaran pengeluaran Dead: 90 hari
• Penghantaran ujian: 30 hari

Simpan log integrasi sendiri apabila anda memerlukan sejarah audit yang lebih panjang. Simpan Event ID dan Delivery ID, tetapi elakkan menyimpan rahsia tanpa keperluan.

Memainkan Semula Penghantaran

Klik “Replay” apabila penghantaran pengeluaran yang telah selesai perlu dicuba lagi.

Replay tersedia untuk penghantaran pengeluaran dalam status Success, Failed atau Dead. Ia tidak tersedia semasa penghantaran Pending dan penghantaran ujian tidak boleh dimainkan semula.

Main semula:

• Mencipta penghantaran Pending baharu.
• Mencipta Delivery ID baharu.
• Mengekalkan Event ID asal.
• Mengekalkan jenis peristiwa dan muatan JSON asal.
• Menggunakan URL sasaran dan petikan pengepala tersuai asal yang disimpan.
• Menggunakan Signing secret semasa apabila permintaan baharu disediakan.

Main semula tidak membina semula muatan daripada data semasa pelanggan. Ia menghantar semula petikan peristiwa asal. Ini menjadikan main semula boleh diaudit dan menghalang peristiwa sejarah daripada berubah makna secara senyap.

Hanya satu main semula bagi penghantaran sumber yang sama boleh berstatus Pending pada satu-satu masa. Tunggu sehingga main semula itu selesai sebelum memintanya lagi.

Pastikan titik akhir Active sebelum memainkan semula. Jika titik akhir tidak aktif, main semula yang berada dalam baris gilir tidak boleh dihantar dengan berjaya.

Oleh sebab penerima mungkin telah menyelesaikan tindakan perniagaan walaupun Maildroppa tidak menerima respons berjaya, main semula boleh menghasilkan permintaan pendua. Deduplikasi Event ID melindungi sistem yang disambungkan daripada mengulangi tindakan tersebut.

Mengedit Titik Akhir

Klik “Edit” untuk menukar URL, pilihan peristiwa, pengepala tersuai atau status aktif.

Sebelum menyimpan:

1. Sahkan bahawa URL baharu telah tersedia.
2. Biarkan nilai pengepala yang disimpan kosong apabila ia perlu dikekalkan.
3. Masukkan nilai baharu untuk setiap pengepala yang dinamakan semula.
4. Semak pilihan peristiwa supaya pemberitahuan yang diperlukan tidak teralih keluar secara tidak sengaja.
5. Simpan dan hantar Test webhook baharu.

Ingat bahawa penghantaran dalam baris gilir mengekalkan URL dan petikan pengepala tersuai sedia ada. Uji konfigurasi baharu untuk penghantaran akan datang dan jangan menganggap ia mengubah permintaan lama yang berada dalam baris gilir.

Menyahaktifkan Titik Akhir

Gunakan suis On/Off apabila anda mahu menjeda integrasi tanpa memadamkan konfigurasi dan sejarahnya.

Apabila titik akhir ditetapkan kepada Off:

• Peristiwa baharu tidak lagi dimasukkan ke dalam baris gilir untuknya.
• Penghantaran Pending yang belum dituntut untuk dihantar ditandakan Failed.
• Test dinyahaktifkan.
• Titik akhir kekal tersedia untuk diedit dan diaktifkan semula kemudian.

Permintaan yang sedang berlangsung ketika penyahaktifan masih boleh selesai. Semak sejarah penghantaran selepas menukar titik akhir kepada Off jika perbezaan ini penting untuk integrasi anda.

Peristiwa yang terlepas ketika titik akhir tidak aktif tidak akan diisi semula apabila anda menghidupkannya semula.

Memadamkan Titik Akhir

Klik “Delete” dan sahkan amaran apabila titik akhir tidak lagi diperlukan.

Pemadaman mengalih keluar titik akhir daripada halaman, menghentikan penghantaran peristiwa akan datang dan menggagalkan penghantaran Pending yang belum dituntut untuk dihantar.

Delete bukan cara untuk menjeda sementara. Gunakan suis On/Off apabila anda mungkin memerlukan konfigurasi atau sejarahnya yang kelihatan semula.

Sebelum memadam, rekodkan sebarang Event ID atau Delivery ID yang masih diperlukan untuk audit integrasi anda.

Penyelesaian Masalah

Titik Akhir Tidak Boleh Disimpan

Semak bahawa:

• URL bermula dengan https://.
• URL menggunakan nama hos awam dan port 443.
• URL tidak mengandungi pemboleh ubah, maklumat log masuk atau fragmen.
• Sekurang-kurangnya satu peristiwa dipilih.
• Setiap Custom header mempunyai nama unik dan nilai.
• Pengepala Maildroppa dan HTTP yang dikhaskan tidak digunakan sebagai nama tersuai.

Test Dinyahaktifkan

Test hanya tersedia untuk titik akhir Active. Hidupkan titik akhir atau editnya dan pilih “Active”, kemudian simpan sebelum menguji.

Test Menunjukkan Tiada Percubaan HTTP

Jana Signing secret jika status ialah Missing. Semak juga sama ada nama hos destinasi adalah awam dan masih diselesaikan dengan betul.

Permintaan boleh ditolak sebelum dihantar apabila rahsia, URL, pengepala tersuai atau pemeriksaan keselamatan destinasi tidak sah.

Penerima Mengembalikan 401 atau 403

Semak nama Custom header dan kelayakan yang disimpan. Edit titik akhir dan masukkan nilai itu semula jika telah berubah.

Pastikan juga penerima tidak keliru antara kelayakan APInya sendiri dengan tandatangan Maildroppa. Pengepala kebenaran tersuai dan X-Maildroppa-Signature mempunyai tujuan berbeza dan boleh diperiksa secara berasingan.

Penerima Mengembalikan Pengalihan

Maildroppa tidak mengikuti pengalihan. Gantikan URL titik akhir dengan URL HTTPS awam akhir dan uji semula.

Tandatangan Tidak Sepadan

Sahkan bahawa penerima:

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

Peristiwa Sama Tiba Lebih Daripada Sekali

Ini boleh berlaku selepas gangguan rangkaian, percubaan semula atau main semula manual. Sistem penghantaran webhook biasanya menyediakan penghantaran sekurang-kurangnya sekali dan bukannya penghantaran tepat sekali.

Gunakan Event ID sebagai kunci idempoten. Kembalikan respons 2xx apabila Event ID yang telah diproses diterima semula dan tiada tindakan tambahan diperlukan.

Penghantaran Berstatus Pending

Lihat “Next retry” dalam lajur HTTP. 408, 429, 5xx atau kegagalan rangkaian sementara yang boleh dicuba semula akan kekal Pending sehingga percubaan berjadual seterusnya.

Klik “Refresh” selepas masa percubaan semula untuk memuatkan status terkini.

Penghantaran Berstatus Dead

Semua percubaan automatik telah digunakan. Baiki penerima terlebih dahulu, pastikan titik akhir Active, hantar Test webhook, kemudian gunakan Replay pada penghantaran pengeluaran.

Senarai Semak Pengeluaran yang Disyorkan

Sebelum bergantung pada titik akhir dalam pengeluaran, sahkan semua perkara berikut:

1. Penerima menggunakan URL HTTPS awam yang stabil dengan sijil yang sah.
2. Signing secret disimpan di luar kod sumber.
3. Tandatangan diperiksa terhadap isi mentah yang tidak diubah.
4. Cap masa lama ditolak mengikut toleransi yang didokumenkan.
5. Penerima menyimpan dan menyahduplikasi Event ID.
6. Penerima logkan Event ID dan Delivery ID untuk penjejakan.
7. Pemprosesan lambat berlaku selepas peristiwa diterima secara tahan lama.
8. Respons 2xx dikembalikan hanya untuk peristiwa yang diterima.
9. Kelayakan tersuai disimpan dalam pengepala dan bukannya URL.
10. Hanya jenis peristiwa yang diperlukan dipilih.
11. Test webhook berjaya dan muncul dengan betul dalam sejarah penghantaran.
12. Pemantauan memberi amaran apabila penghantaran pengeluaran mula mengembalikan ralat.

Dengan perlindungan ini tersedia, halaman Webhook menyediakan kedua-dua sisi integrasi yang boleh dipercayai: penghantaran peristiwa yang selamat kepada aplikasi anda dan sejarah operasi yang jelas dalam Maildroppa.