Konfigurasikan webhook

Diterbitkan: 16 Julai 2026 · Kemas kini terakhir: 12 September 2026 · Oleh Marcus Biel

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

Aplikasi anda tidak perlu menyemak dengan Maildroppa berulang kali sama ada pelanggan telah dicipta, dikemas kini, berhenti melanggan atau diberikan teg. Sebaliknya, aplikasi boleh menerima permintaan HTTPS sejurus selepas peristiwa itu berlaku.

Halaman “Webhooks” ialah pusat kawalan untuk integrasi yang meliputi seluruh akaun ini. Anda boleh mencipta beberapa titik akhir, memilih peristiwa yang diterima oleh setiap titik akhir, menambah pengepala pengesahan, menguji sambungan, menyemak percubaan penghantaran dan menghantar semula peristiwa produksi apabila perlu.

Cara webhook akaun berfungsi

Webhook akaun mengikuti proses ini:

1. Peristiwa berlaku dalam Maildroppa, contohnya apabila 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 menggunakan rahsia tandatangan webhook akaun anda.
5. Maildroppa menghantar permintaan HTTPS POST ke URL titik akhir yang disimpan.
6. Titik akhir anda mengesahkan tandatangan, menyimpan atau memproses peristiwa, kemudian mengembalikan respons HTTP.
7. Maildroppa merekodkan hasilnya dalam sejarah penghantaran dan mencuba semula penghantaran yang mengalami kegagalan sementara secara automatik.

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

Webhook akaun berbeza daripada langkah “Send a webhook” dalam automasi. Webhook akaun memantau peristiwa akaun yang dipilih di seluruh Maildroppa. Webhook automasi pula dihantar hanya apabila pelanggan mencapai langkah tertentu itu. Kedua-duanya menggunakan rahsia tandatangan webhook akaun. Oleh itu, penggiliran rahsia menjejaskan setiap penerima webhook keluar yang mengesahkan tandatangan Maildroppa.

Buka halaman Webhooks

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

Halaman ini mengandungi tiga bahagian utama:

• Signing secret
• Endpoints
• Delivery history untuk titik akhir yang dipilih

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

Sebelum mencipta titik akhir

Sediakan penerima pada pelayan anda sebelum mengkonfigurasikan 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.
• Memberikan respons dengan cepat, bukan menjalankan kerja yang mengambil masa semasa permintaan diproses.

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

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

Langkah 1: Jana rahsia tandatangan

Setiap permintaan webhook Maildroppa ditandatangani. Penerima anda menggunakan rahsia tandatangan 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 status berikut:

• Missing — Rahsia tandatangan belum wujud.
• Ready — Rahsia tandatangan telah dikonfigurasikan.
• Loading — Maildroppa sedang mendapatkan status semasa.

Klik “Generate secret” apabila statusnya Missing.

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

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

Jika rahsia hilang

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

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

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

Lindungi rahsia seperti kata laluan

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

Hanya penerima pada bahagian pelayan memerlukan rahsia tersebut. Jika anda mengesyaki rahsia itu telah terdedah, lakukan penggiliran rahsia dan kemas kini semua penerima dengan segera.

Sahkan tandatangan webhook

Setiap permintaan mengandungi pengepala Maildroppa berikut:

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

Maildroppa turut menghantar:

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

Tandatangan menggunakan format berikut:

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 rahsia tandatangan sebagai kunci HMAC.

Contoh Node.js berikut menunjukkan langkah pengesahan utama. rawBody mestilah bait permintaan asal, bukan JSON yang telah dihuraikan dan disirikan 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 yang berada di luar julat toleransi masa singkat yang dipilih untuk infrastruktur anda, contohnya lima minit. Ini mengurangkan risiko permintaan sah yang telah dirakam dihantar semula jauh lebih lewat.

Huraikan dan proses JSON hanya selepas kedua-dua semakan berjaya.

Punca lazim ralat tandatangan

Pengesahan tandatangan biasanya gagal atas salah satu sebab berikut:

• Penerima menggunakan rahsia lama selepas penggiliran.
• Perisian perantara menghuraikan atau mengubah JSON sebelum tandatangan dikira.
• Penerima hanya menandatangani isi tanpa menyertakan <timestamp>..
• Cap masa dianggap sebagai tarikh berformat, bukan nilai pengepala yang tepat.
• Awalan v1= tidak disertakan dalam perbandingan.
• HMAC yang dikira menggunakan pengekodan lain, bukan heksadesimal huruf kecil.

Rekodkan Event ID dan Delivery ID dalam log apabila pengesahan gagal, tetapi jangan sekali-kali merekodkan rahsia tandatangan 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 Active

Titik akhir baharu ditetapkan kepada Active dan semua peristiwa yang dipaparkan dalam editor dipilih pada mulanya. Semak pilihan tersebut sebelum menyimpan supaya penerima hanya mendapat pemberitahuan yang diperlukan.

Konfigurasikan URL titik akhir

Masukkan URL awam penuh yang akan menerima permintaan Maildroppa, contohnya:

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

URL mesti memenuhi keperluan berikut:

• Mesti menggunakan https://.
• Mesti mengandungi nama hos awam yang sah.
• Panjangnya tidak boleh melebihi 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 diresolusikan 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. Sebaliknya, gunakan pengepala tersuai untuk bukti kelayakan.

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

Nama hos destinasi diresolusikan semula sebelum penghantaran. Nama hos yang kemudiannya diresolusikan kepada alamat peribadi atau alamat yang disekat akan ditolak, walaupun nama hos itu sah ketika titik akhir disimpan.

Pilih 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 mengambil kira kebenaran.

Jangan anggap peristiwa ini sebagai bukti bahawa setiap pendaftaran telah melengkapkan pengesahan langganan melalui e-mel (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 yang lengkap dalam muatan sebagai gambaran semasa pelanggan dalam Maildroppa. Jangan anggap bahawa hanya satu sifat tertentu telah berubah.

Pemberian dan pengalihan keluar teg mempunyai jenis peristiwa tersendiri supaya kedua-duanya boleh dikendalikan secara berasingan.

Subscriber Unsubscribed — subscriber.unsubscribed

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

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

Tag Added — subscriber.tag_added

Dihantar apabila teg diberikan kepada pelanggan.

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

Tag Removed — subscriber.tag_removed

Dihantar apabila teg dialih keluar daripada pelanggan.

Muatan mengandungi pelanggan yang dikemas kini dan teg yang dialih keluar. Teg yang dialih keluar disertakan secara berasingan walaupun teg itu tidak lagi terdapat dalam tatasusunan tags semasa pelanggan.

Form Submitted — form.submitted

Dihantar apabila pelawat menghantar borang pendaftaran Maildroppa.

Anggap peristiwa ini sebagai isyarat penghantaran borang, bukan pengesahan bahawa proses pengesahan langganan melalui e-mel (double opt-in) telah selesai. Sebarang aliran kerja yang memerlukan langganan disahkan mesti terus mematuhi status semasa pelanggan dan proses pengesahan.

Gunakan titik akhir berasingan untuk tanggungjawab yang berbeza

Anda boleh menghantar peristiwa berbeza kepada sistem berbeza. Contohnya:

• Hantar peristiwa pelanggan dan teg kepada CRM.
• Hantar peristiwa berhenti melanggan kepada perkhidmatan sekatan penghantaran.
• Hantar peristiwa penghantaran borang kepada saluran pemprosesan 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 tersendiri.

Tambah pengepala tersuai

Pengepala tersuai tidak wajib. Gunakannya apabila penerima memerlukan kunci API, token pembawa, pengecam penyewa atau pengepala tetap yang lain.

Klik “Add header”, kemudian isikan “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:

• Wajib diisi.
• Boleh mengandungi sehingga 128 aksara.
• Mesti menggunakan aksara yang sah untuk nama pengepala HTTP.
• Mesti unik tanpa mengambil kira huruf besar atau huruf kecil.

Nilai pengepala:

• Wajib diisi.
• 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 medan itu kosong untuk mengekalkan rahsia sedia ada. Masukkan nilai baharu untuk menggantikannya.

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

Jika anda mengalih keluar baris pengepala, pengepala itu tidak lagi disertakan dalam penghantaran akan datang selepas titik akhir disimpan.

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

Tetapkan titik akhir kepada aktif atau tidak aktif

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

Nyahpilih “Active” jika anda mahu menyimpan konfigurasi tanpa memulakan penghantaran. Anda boleh mengaktifkan titik akhir kemudian melalui senarai titik akhir.

Titik akhir yang tidak aktif:

• Tidak menerima peristiwa baharu yang berlaku.
• Tidak boleh menghantar webhook ujian.
• Kekal dipaparkan dan boleh diedit.
• Mengekalkan akses kepada sejarah penghantaran sedia ada.

Mengaktifkan titik akhir tidak akan menghantar peristiwa yang berlaku semasa titik akhir itu tidak aktif.

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

Fahami senarai titik akhir

Setiap baris titik akhir memaparkan:

• 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 serta-merta 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 salinan URL titik akhir, muatan dan pengepala tersuai sebagaimana keadaannya pada waktu itu.

Mengedit URL atau pengepala tersuai menjejaskan penghantaran yang baru dicipta sahaja. Penghantaran yang sudah 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 retroaktif untuk jenis peristiwa yang tidak dipilih ketika peristiwa berlaku.

Rahsia tandatangan berbeza: nilainya dibaca apabila permintaan HTTP disediakan. Oleh itu, penghantaran yang menunggu atau penghantaran semula peristiwa boleh menggunakan rahsia tandatangan yang baru digilirkan, walaupun muatan dan salinan konfigurasi titik akhirnya dicipta lebih awal.

Uji titik akhir

Klik “Test” pada titik akhir aktif selepas penerima dan rahsia tandatangan tersedia.

Maildroppa menghantar satu permintaan bertandatangan serta-merta menggunakan URL titik akhir dan pengepala tersuai yang disimpan. Perubahan yang belum disimpan dalam editor yang terbuka tidak disertakan 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 dimasukkan ke dalam jadual percubaan semula produksi dan peristiwanya tidak boleh dihantar semula.

Selepas permintaan selesai, panel hasil memaparkan:

• 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 respons

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

Fahami muatan produksi

Peristiwa akaun dalam persekitaran produksi menggunakan struktur pembungkus JSON yang sama:

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

Sifat pada peringkat teratas membawa maksud berikut:

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

Halakan peristiwa berdasarkan nilai type yang tepat. Abaikan sifat tambahan yang tidak diperlukan oleh integrasi anda supaya penambahan yang serasi pada muatan tidak menjejaskan fungsi 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 bernilai null apabila tiada nilai wujud. Oleh itu, penerima anda perlu mengikuti skema muatan dan tidak menganggap bahawa setiap nilai profil pilihan sentiasa ada.

Muatan peristiwa teg

Peristiwa teg mengandungi pelanggan serta teg yang mencetuskan peristiwa itu:

{
  "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 teg 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. ID ini muncul dalam:

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

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

Percubaan semula dan penghantaran semula peristiwa secara manual juga mengekalkan Event ID asal. Simpan Event ID yang telah diproses dan pastikan tindakan perniagaan bersifat idempoten supaya permintaan berulang tidak mencipta kenalan pendua, mengulangi tindakan yang tidak boleh dibatalkan atau menerapkan perubahan yang sama dua kali.

Delivery ID

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

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

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

Gunakan Delivery ID untuk penjejakan teknikal dan sokongan. Gunakan Event ID untuk mengelakkan pendua pada peringkat perniagaan.

Kembalikan 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 yang boleh dicuba semula.
• Kegagalan rangkaian yang mungkin bersifat sementara akan dicuba semula.
• Pengalihan dan respons 3xx lain tidak diikuti dan dianggap sebagai kegagalan muktamad.
• Respons 4xx lain dianggap sebagai kegagalan muktamad 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 menjalankan kerja yang lebih lambat secara tak segerak.

Jangan kembalikan pengalihan ke URL webhook lain. Sebaliknya, konfigurasikan URL akhir dalam Maildroppa.

Jadual percubaan semula automatik

Penghantaran produksi boleh membuat sehingga tujuh percubaan HTTP.

Selepas kegagalan yang boleh dicuba semula, Maildroppa menjadualkan percubaan seterusnya dengan sela masa 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 mengalami kegagalan yang boleh dicuba semula, penghantaran bertukar kepada status Dead dan tiada percubaan automatik seterusnya dijadualkan.

Sela masa dikira dari setiap percubaan yang gagal. Penghantaran sebenar mungkin berlaku sedikit lewat kerana penghantaran diproses secara tak segerak dan turut tertakluk pada had perlindungan sistem.

Jika boleh, baiki masalah sementara pada penerima sebelum waktu “Next retry” yang dipaparkan. Jika percubaan automatik telah tamat, gunakan “Replay” selepas penerima kembali berfungsi dengan baik.

Fahami sejarah penghantaran

Sejarah penghantaran merujuk kepada titik akhir yang sedang dipilih. URL titik akhir muncul pada pengepala bahagian supaya anda boleh memastikan sejarah yang sedang dilihat.

Gunakan penapis berikut:

• All — Memaparkan penghantaran produksi dan ujian.
• Production — Memaparkan penghantaran peristiwa sebenar sahaja.
• Test — Memaparkan ujian manual sahaja.

Klik “Refresh” untuk mendapatkan status terkini. Paparan sejarah tidak perlu dibiarkan terbuka semasa Maildroppa menghantar atau mencuba semula penghantaran.

Halaman ini memaparkan 50 penghantaran terkini yang sepadan dengan penapis yang dipilih.

Lajur penghantaran

Setiap baris mengandungi:

• Created — Masa rekod penghantaran dicipta.
• State — Pending, Success, Failed atau Dead.
• HTTP — Status respons, bilangan percubaan dan tempoh, serta masa percubaan semula seterusnya jika berkenaan.
• Subscriber — Alamat 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 memaparkan “No HTTP attempt”. Ini boleh berlaku apabila Maildroppa menolak permintaan sebelum penghantaran, contohnya kerana rahsia tandatangan tiada atau destinasi yang disimpan tidak lagi boleh digunakan dengan selamat.

Jika tersedia, baris turut memaparkan “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 seterusnya 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 sempat dihantar.

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

Tempoh penyimpanan sejarah

Rekod penghantaran disimpan untuk tempoh terhad:

• Penghantaran produksi berjaya: 30 hari
• Penghantaran produksi gagal: 90 hari
• Penghantaran produksi berstatus Dead: 90 hari
• Penghantaran ujian: 30 hari

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

Hantar semula peristiwa

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

“Replay” tersedia untuk penghantaran produksi berstatus Success, Failed atau Dead. Tindakan ini tidak tersedia semasa penghantaran berstatus Pending, dan peristiwa ujian tidak boleh dihantar semula.

Penghantaran semula peristiwa:

• Mencipta penghantaran baharu berstatus Pending.
• Mencipta Delivery ID baharu.
• Mengekalkan Event ID asal.
• Mengekalkan jenis peristiwa dan muatan JSON asal.
• Menggunakan URL sasaran asal dan salinan pengepala tersuai asal yang disimpan.
• Menggunakan rahsia tandatangan semasa apabila permintaan baharu disediakan.

Penghantaran semula tidak membina semula muatan daripada data semasa pelanggan. Sebaliknya, salinan peristiwa asal dihantar semula. Ini membolehkan penghantaran semula diaudit dan menghalang makna peristiwa terdahulu daripada berubah tanpa disedari.

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

Pastikan titik akhir berstatus Active sebelum menghantar semula peristiwa. Jika titik akhir tidak aktif, penghantaran semula yang berada dalam baris gilir tidak dapat dihantar dengan berjaya.

Penerima mungkin telah menyelesaikan tindakan perniagaan walaupun Maildroppa tidak menerima respons berjaya daripadanya. Oleh itu, penghantaran semula boleh menghasilkan permintaan pendua. Penyahduplikasian berdasarkan Event ID melindungi sistem yang disambungkan daripada mengulangi tindakan tersebut.

Edit titik akhir

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

Sebelum menyimpan:

1. Pastikan URL baharu sudah boleh dicapai.
2. Biarkan medan nilai pengepala yang disimpan kosong jika nilainya perlu dikekalkan.
3. Masukkan nilai baharu untuk setiap pengepala yang ditukar namanya.
4. Semak pilihan peristiwa supaya pemberitahuan yang diperlukan tidak teralih keluar secara tidak sengaja.
5. Simpan dan hantar webhook ujian baharu.

Ingat bahawa penghantaran dalam baris gilir mengekalkan URL dan salinan pengepala tersuai sedia ada. Uji konfigurasi baharu untuk penghantaran akan datang. Jangan anggap konfigurasi itu turut mengubah permintaan lama dalam baris gilir.

Nyahaktifkan titik akhir

Gunakan suis “On/Off” untuk menjeda integrasi tanpa memadamkan konfigurasi dan sejarahnya.

Apabila titik akhir ditetapkan kepada Off:

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

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

Peristiwa yang terlepas semasa titik akhir tidak aktif tidak akan dihantar apabila anda menetapkannya semula kepada On.

Padamkan 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 menetapkan penghantaran berstatus Pending yang belum diambil untuk dihantar sebagai gagal.

“Delete” bukan cara untuk menjeda integrasi buat sementara waktu. Gunakan suis “On/Off” jika anda mungkin memerlukan konfigurasi atau paparan sejarahnya semula.

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

Penyelesaian masalah

Titik akhir tidak dapat disimpan

Pastikan:

• 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 pengepala tersuai mempunyai nama yang unik dan nilai.
• Nama pengepala Maildroppa dan HTTP yang dikhaskan tidak digunakan sebagai nama pengepala tersuai.

Test dinyahaktifkan

“Test” hanya tersedia untuk titik akhir berstatus Active. Tetapkan titik akhir kepada On atau edit titik akhir dan pilih “Active”, kemudian simpan sebelum menguji.

Test memaparkan No HTTP attempt

Jana rahsia tandatangan jika statusnya Missing. Semak juga sama ada nama hos destinasi ialah nama hos awam dan masih diresolusikan dengan betul.

Permintaan boleh ditolak sebelum penghantaran jika rahsia, URL atau pengepala tersuainya tidak sah, atau jika semakan keselamatan destinasi gagal.

Penerima mengembalikan 401 atau 403

Semak nama pengepala tersuai dan bukti kelayakan yang disimpan. Edit titik akhir dan masukkan nilainya semula jika nilai itu telah berubah.

Pastikan juga penerima tidak tersalah anggap bukti kelayakan APInya sendiri sebagai tandatangan Maildroppa. Pengepala kebenaran tersuai dan X-Maildroppa-Signature mempunyai tujuan yang berbeza dan boleh disemak secara berasingan.

Penerima mengembalikan pengalihan

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

Tandatangan tidak sepadan

Pastikan penerima:

• Menggunakan rahsia tandatangan semasa.
• Menggunakan nilai X-Maildroppa-Timestamp yang tepat.
• Menandatangani <timestamp>.<raw request body>.
• Menggunakan HMAC-SHA256 dan output heksadesimal huruf kecil.
• Membandingkan nilai penuh termasuk v1=.
• Membuat perbandingan sebelum penghuraian JSON mengubah isi permintaan.

Peristiwa yang sama tiba lebih daripada sekali

Ini boleh berlaku selepas gangguan rangkaian, percubaan semula atau penghantaran semula peristiwa secara manual. Sistem penghantaran webhook lazimnya menyediakan penghantaran sekurang-kurangnya sekali, bukan tepat sekali.

Gunakan Event ID sebagai kunci idempotensi. 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. Penghantaran yang mengalami kegagalan 408, 429, 5xx atau kegagalan rangkaian sementara yang boleh dicuba semula akan kekal berstatus Pending sehingga percubaan berjadual seterusnya.

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

Penghantaran berstatus Dead

Semua percubaan automatik telah digunakan. Baiki penerima terlebih dahulu, pastikan titik akhir berstatus Active, hantar webhook ujian, kemudian gunakan “Replay” pada penghantaran produksi.

Senarai semak produksi yang disyorkan

Sebelum bergantung pada titik akhir dalam persekitaran produksi, pastikan semua perkara berikut dipenuhi:

1. Penerima menggunakan URL HTTPS awam yang stabil dengan sijil yang sah.
2. Rahsia tandatangan disimpan di luar kod sumber.
3. Tandatangan disemak berdasarkan isi mentah yang tidak diubah.
4. Cap masa lama ditolak mengikut julat toleransi yang didokumenkan.
5. Penerima menyimpan dan menyahduplikasi Event ID.
6. Penerima merekodkan Event ID dan Delivery ID dalam log untuk penjejakan.
7. Pemprosesan yang mengambil masa dijalankan selepas peristiwa diterima dan disimpan secara tahan lama.
8. Respons 2xx dikembalikan hanya untuk peristiwa yang telah diterima.
9. Bukti kelayakan tersuai disimpan dalam pengepala, bukan URL.
10. Hanya jenis peristiwa yang diperlukan dipilih.
11. Webhook ujian berjaya dan dipaparkan dengan betul dalam sejarah penghantaran.
12. Pemantauan memberikan amaran apabila penghantaran produksi mula mengembalikan ralat.

Dengan langkah perlindungan ini, halaman “Webhooks” menyediakan dua aspek penting bagi integrasi yang boleh diandalkan: penghantaran peristiwa yang selamat kepada aplikasi anda dan sejarah operasi yang jelas dalam Maildroppa.