Webhook event

Webhook mengirim event email ke server Anda. Konfigurasi callback berada di tingkat API Key dan saat ini memerlukan operator platform; konsol pelanggan tidak memiliki halaman mandiri untuk URL Webhook, langganan, rahasia tanda tangan, atau log pengiriman.

Sebelum aktivasi

• Sediakan URL callback HTTPS yang dapat diakses publik dengan sertifikat valid. URL yang mengarah ke alamat privat, loopback, link-local, atau alamat cadangan lainnya akan ditolak.
• Konfirmasikan tipe event dan mode autentikasi callback.
• Pastikan penerima mengembalikan 2xx dalam 10 detik tanpa bergantung pada redirect, cookie, atau percobaan ulang otomatis.
• Terapkan deduplikasi berdasarkan eventId dan rekonsiliasi berdasarkan Message ID.

Event yang dapat dilanggan

Event buka dan klik bergantung pada dukungan serta konfigurasi pelacakan kanal. send_failed adalah event tingkat pesan dan memiliki string recipient kosong.

Format permintaan

Platform mengirim POST dengan Content-Type: application/json. Header umum meliputi:

• X-Innomail-Event: tipe event;
• X-Innomail-Event-Id: identitas tugas event yang sesuai dengan eventId dalam body.

Contoh body:

{
  "eventId": "EVENT-EXAMPLE-001",
  "eventType": "delivered",
  "messageId": "SINGLE-EXAMPLE-001",
  "recipient": "alice@example.net",
  "occurredAt": "2026-11-11T03:00:00Z",
  "reasonCode": "",
  "reasonMessage": ""
}

Perlakukan setiap field sebagai string. reasonCode dan reasonMessage dapat kosong. Event penyedia dan event kegagalan Sender memperoleh alasan dari sumber berbeda dan tidak menggunakan satu tabel kode yang sama.

Memverifikasi tanda tangan callback

Platform mengonfigurasi salah satu mode berikut untuk API Key. Gunakan mode dan encoding yang diberikan saat aktivasi, dan jangan pernah mencatat rahasia sebenarnya.

X-CALLBACK-ID

Format header:

X-CALLBACK-ID: timestamp=<milliseconds>;nonce=<random>;username=<username>;signature=<signature>

Perhitungan:

signature = HMAC-SHA256(webhookSigningSecret, timestamp + nonce + username)

Gabungkan tiga nilai tanpa pemisah. Output default adalah hex huruf kecil; Base64 dapat dikonfigurasi oleh platform. Hitung ulang menggunakan timestamp, nonce, dan username persis seperti yang diterima, bandingkan dalam constant time, dan validasi kesegaran timestamp.

Mode kompatibilitas: X-Innomail-Signature

Jika username Webhook dan rahasia tanda tangan khusus tidak dikonfigurasi, mode kompatibilitas dapat digunakan:

signKey = HMAC-SHA256(apiSecret, "innomail-webhook-v1")
material = X-Innomail-Timestamp + "." + X-Innomail-Event-Id + "." + rawBody
X-Innomail-Signature = "sha256=" + lowercaseHex(HMAC-SHA256(signKey, material))

rawBody harus berupa byte persis yang diterima; jangan memformat JSON terlebih dahulu. Kunci tanda tangan diturunkan, bukan menggunakan API Secret secara langsung sebagai kunci HMAC pesan.

Idempotensi dan respons

• Gunakan eventId dalam body sebagai kunci deduplikasi event dan simpan hasil pemrosesan.
• Satu messageId dapat memiliki beberapa eventType berbeda yang sah, jadi jangan deduplikasi hanya berdasarkan Message ID.
• Kembalikan 2xx setelah pemrosesan berhasil, atau simpan terlebih dahulu dan proses secara asinkron.
• Setiap tugas saat ini hanya dicoba sekali. Kegagalan koneksi, timeout, dan respons non-2xx tidak dicoba ulang atau diputar ulang secara otomatis.
• Jangan bergantung pada penjelasan lama bahwa ID CB- dan CBRT- tiba berpasangan, dan jangan menunggu percobaan ulang otomatis yang tidak tersedia.

Menelusuri event yang tidak diterima

1. Pastikan API Key yang benar telah dikonfigurasi oleh platform dengan URL callback, status aktif, dan langganan event.
2. Periksa DNS publik, sertifikat HTTPS, alamat hasil resolusi, dan waktu respons 10 detik.
3. Periksa mode tanda tangan, raw body, satuan timestamp, dan encoding hex/Base64.
4. Bandingkan dengan catatan pengiriman untuk memastikan event benar-benar terjadi; event buka dan klik juga memerlukan dukungan pelacakan kanal.
5. Hubungi operator platform dengan Message ID, eventId, waktu kejadian, dan log penerima. Pelanggan saat ini tidak memiliki kueri log pengiriman Webhook atau antarmuka replay manual.

Kode kegagalan Sender

Lihat Kode kegagalan Sender.

Pertanyaan umum

Mengapa tidak ada pengiriman ulang otomatis?

Setiap tugas Webhook saat ini dicoba sekali. Kegagalan koneksi, timeout, dan respons non-2xx tidak dicoba ulang atau diputar ulang. Jaga penerima tetap tersedia, simpan event sebelum memproses secara asinkron, dan cocokkan dengan catatan pengiriman.

Bisakah satu pesan memiliki beberapa event?

Ya. Satu messageId dapat memiliki beberapa jenis event. Deduplikasi berdasarkan eventId, bukan Message ID.

Mengapa verifikasi tanda tangan gagal?

Periksa mode yang dikonfigurasi, byte raw body yang tepat, satuan timestamp, serta encoding hex atau Base64. Dalam mode kompatibilitas, kunci penandatanganan pesan diturunkan dari API Secret.

Sumber terkait