Webhook

Cloudin POST event ke URL kamu setiap email masuk (atau event lain yang kamu subscribe). Delivery dikirim near-real-time — biasanya beberapa detik setelah email masuk, bukan polling lambat. Cocok buat bot yang nungguin OTP.

Setup

1. Buka Layanan → Webhook → Tambah webhook
2. Input URL endpoint kamu
3. Pilih event types
4. Secret muncul sekali — catat untuk verify HMAC

Event types

• message.received — email baru masuk
• message.deleted — email dihapus
• address.created — address baru di-generate
• domain.verified — DNS verify OK
• domain.lost — DNS verify gagal 3x
• service.suspended / service.reactivated — billing state

Payload format

{
  "id": "evt_01HXY...",
  "type": "message.received",
  "created_at": "2026-05-28T07:00:00Z",
  "data": {
    "message": {
      "id": "msg_01HXY...",
      "address": "abc@inbox.brandkamu.id",
      "from": "sender@example.com",
      "from_name": "OpenAI",
      "subject": "Verifikasi Email",
      "preview": "Klik link...",
      "otp_code": "918203"
    }
  }
}

otp_code otomatis di-ekstrak dari email verifikasi (angka maupun alfanumerik, mis. 918203 atau G7K2PX). null kalau nggak ada kode terdeteksi.

Filter pengiriman (per-webhook)

Biar bot cuma di-ping untuk email yang relevan, tiap webhook bisa difilter:

• Cuma OTP (filterOtpOnly: true) — webhook hanya fire kalau email punya otp_code. Cocok buat automasi signup yang cuma butuh kode verifikasi.
• Dari domain tertentu (filterFromDomain: "openai.com") — webhook hanya fire kalau domain pengirim mengandung nilai ini. Kosong = semua pengirim.

Verify signature (HMAC SHA256)

Setiap delivery dikirim dengan header:

• X-Cloudin-Timestamp — Unix timestamp
• X-Cloudin-Signature — sha256= atas ${timestamp}.${rawBody}
• X-Cloudin-Event — tipe event (mis. message.received)
• X-Cloudin-Delivery — ID delivery unik (dedup / korelasi)

const crypto = require('crypto');
function verifyWebhook(rawBody, timestamp, signature, secret) {
  // Reject kalau >5 menit (anti-replay)
  if (Math.abs(Date.now()/1000 - parseInt(timestamp)) > 300) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(${timestamp}.${rawBody})
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry policy

Webhook delivery retry exponential backoff:

Timeout per delivery: 10 detik. Status sukses: HTTP 2xx-3xx (kecuali 307/308).

Kelola webhook via API

Endpoint webhook CRUD memakai Bearer JWT (dashboard) — bukan API key. :id di path create/list = ID layanan.

{
  "url": "https://kamu.id/webhook",
  "events": ["message.received"],
  "enabled": true,
  "filterOtpOnly": false,
  "filterFromDomain": null,
  "allowedIps": []
}

• events — minimal 1, dari daftar event di atas.
• allowedIps — opsional, maksimal 10 IP; kalau diisi, hanya IP itu yang diterima worker sebagai sumber verifikasi. URL private/loopback ditolak (BAD_REQUEST).
• Melewati batas 5 webhook per layanan → 429 QUOTA_EXCEEDED.
• Retry delivery yang sudah success → 409 CONFLICT.