Webhooks

Daftarkan endpoint HTTP untuk menerima notifikasi event real-time. Periksa log pengiriman dan pantau aktivitas di langganan webhook Anda.

ⓘ

Semua request memerlukan header x-api-key. Base URL untuk setiap endpoint adalah https://api.agentsend.io.

Objek Webhook

Setiap endpoint yang mengembalikan webhook mengembalikan bentuk ini. Field secret hanya disertakan dalam respons untuk POST /webhooks — simpan dengan aman, karena tidak dapat diambil lagi.

json

{
  "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "url": "https://your-app.com/webhooks/agentsend",
  "description": "Production inbound handler",
  "events": ["message.received", "message.bounced"],
  "isActive": true,
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T10:00:00.000Z"
}

Field	Tipe	Deskripsi
`id`	string (uuid)	Pengenal webhook unik.
`url`	string (uri)	Endpoint HTTPS tempat AgentSend mengirimkan event.
`description`	string \| null	Label yang dapat dibaca manusia opsional untuk webhook.
`events`	string[] \| null	Array tipe event yang dilanggani. `null` atau array kosong berarti semua event dikirim.
`isActive`	boolean	Apakah webhook saat ini menerima event.
`createdAt`	string (ISO 8601)	Saat webhook dibuat.
`updatedAt`	string (ISO 8601)	Saat webhook terakhir diperbarui.

Buat Webhook

POST /webhooks

Register a new webhook endpoint. Returns 201 Created with the Webhook object plus a secret field. Use the secret to verify webhook signatures — it is only returned once and cannot be retrieved later.

Body Request

Parameter	Tipe	Deskripsi
`url` wajib	string (uri)	URL HTTPS yang akan digunakan AgentSend untuk POST event. Harus URI valid yang dimulai dengan `https://`.
`description`	string	Label yang dapat dibaca manusia untuk mengidentifikasi webhook ini di dasbor dan log.
`events`	string[]	Daftar tipe event yang dilanggani. Hilangkan atau teruskan array kosong untuk menerima semua event. Nilai valid: `domain.verified`, `message.received`, `message.sent`, `message.delivered`, `message.bounced`, `message.complained`.

Contoh Request

javascript

const res = await fetch("https://api.agentsend.io/webhooks", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-app.com/webhooks/agentsend",
    description: "Production inbound handler",
    events: ["message.received", "message.bounced"],
  }),
});

const webhook = await res.json();
console.log(webhook.secret); // Save this — it won't be shown again

Respons — 201 Created

json

{
  "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "url": "https://your-app.com/webhooks/agentsend",
  "description": "Production inbound handler",
  "events": ["message.received", "message.bounced"],
  "isActive": true,
  "secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T10:00:00.000Z"
}

⚠

secret hanya dikembalikan pada pembuatan. Simpan di variabel lingkungan yang aman segera — Anda tidak dapat mengambilnya lagi melalui API.

Daftar Webhook

GET /webhooks

Mengembalikan semua webhook yang terdaftar untuk akun Anda. Secret tidak pernah disertakan dalam respons daftar atau ambil.

Contoh Request

javascript

const res = await fetch("https://api.agentsend.io/webhooks", {
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});

const { data } = await res.json();
console.log(`${data.length} webhooks registered`);

Respons — 200 OK

json

{
  "data": [
    {
      "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
      "url": "https://your-app.com/webhooks/agentsend",
      "description": "Production inbound handler",
      "events": ["message.received", "message.bounced"],
      "isActive": true,
      "createdAt": "2026-04-16T10:00:00.000Z",
      "updatedAt": "2026-04-16T10:00:00.000Z"
    }
  ]
}

Ambil Katalog Event

GET /webhooks/catalog

Mengembalikan daftar lengkap tipe event yang dapat dilanggani webhook Anda, termasuk nama dan deskripsinya. Gunakan ini untuk mengisi UI pemilih event atau memvalidasi nama event saat runtime.

Contoh Request

javascript

const res = await fetch("https://api.agentsend.io/webhooks/catalog", {
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});

const { data } = await res.json();
data.forEach(e => console.log(e.name, e.description));

Respons — 200 OK

json

{
  "data": [
    {
      "name": "domain.verified",
      "description": "Fired when a custom domain passes DNS verification."
    },
    {
      "name": "message.received",
      "description": "Fired when an inbound email arrives in an inbox."
    },
    {
      "name": "message.sent",
      "description": "Fired when an outbound message is accepted by the recipient mail server."
    },
    {
      "name": "message.delivered",
      "description": "Fired when delivery to the recipient mailbox is confirmed."
    },
    {
      "name": "message.bounced",
      "description": "Fired when a message hard-bounces."
    },
    {
      "name": "message.complained",
      "description": "Fired when a recipient marks the message as spam."
    }
  ]
}

Daftar Log Pengiriman

GET /webhooks/logs

Mengembalikan daftar percobaan pengiriman webhook individu, diurutkan berdasarkan yang terbaru dulu. Gunakan ini untuk men-debug pengiriman yang gagal, memeriksa payload, dan meninjau kode respons dari endpoint Anda.

Parameter Query

Parameter	Tipe	Deskripsi
`webhookId`	string (uuid)	Filter log ke webhook tertentu. Jika dihilangkan, log untuk semua webhook dikembalikan.
`status`	enum	Filter berdasarkan hasil pengiriman. Salah satu dari `success` atau `failed`.
`event`	string	Filter berdasarkan tipe event, misalnya `message.received`.
`limit`	integer	Jumlah maksimum entri log yang dikembalikan. Default `20`.
`hours`	integer	Jendela lihat-kembali dalam jam. Default `168` (7 hari).

Contoh Request

javascript

const params = new URLSearchParams({
  webhookId: "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  status: "failed",
  limit: "50",
  hours: "24",
});

const res = await fetch(
  `https://api.agentsend.io/webhooks/logs?${params}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data } = await res.json();
data.forEach(log => console.log(log.event, log.responseStatus));

Respons — 200 OK

json

{
  "data": [
    {
      "id": "whl_01hx9k2v3w4x5y6z7a8b9c0d",
      "webhookId": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
      "event": "message.received",
      "status": "failed",
      "responseStatus": 503,
      "durationMs": 4821,
      "attempts": 3,
      "createdAt": "2026-04-16T11:05:00.000Z"
    }
  ]
}

Ambil Aktivitas

GET /webhooks/activity

Mengembalikan aktivitas pengiriman teragregasi (jumlah sukses dan gagal seiring waktu) untuk satu atau semua webhook. Berguna untuk merender grafik di dasbor pemantauan.

Parameter Query

Parameter	Tipe	Deskripsi
`webhookId`	string (uuid)	Batasi aktivitas ke webhook tertentu. Jika dihilangkan, aktivitas di semua webhook dikembalikan.
`hours`	integer	Jendela lihat-kembali dalam jam. Default `6`.

Contoh Request

javascript

const res = await fetch(
  "https://api.agentsend.io/webhooks/activity?webhookId=wh_01hx9k2v3w4x5y6z7a8b9c0d&hours=24",
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const activity = await res.json();
console.log(activity.successCount, activity.failureCount);

Respons — 200 OK

json

{
  "webhookId": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "hours": 24,
  "successCount": 142,
  "failureCount": 3,
  "buckets": [
    { "timestamp": "2026-04-15T11:00:00.000Z", "success": 18, "failure": 0 },
    { "timestamp": "2026-04-15T12:00:00.000Z", "success": 24, "failure": 1 }
  ]
}

Ambil Webhook

GET /webhooks/{id}

Ambil satu webhook berdasarkan ID-nya. Secret tidak pernah dikembalikan setelah pembuatan.

Path Parameters

Parameter	Tipe	Deskripsi
`id` wajib	string (uuid)	ID webhook untuk diambil.

Contoh Request

javascript

const res = await fetch(
  `https://api.agentsend.io/webhooks/${webhookId}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const webhook = await res.json();
console.log(webhook.isActive, webhook.events);

Respons — 200 OK

Mengembalikan satu objek Webhook (tanpa secret).

json

{
  "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "url": "https://your-app.com/webhooks/agentsend",
  "description": "Production inbound handler",
  "events": ["message.received", "message.bounced"],
  "isActive": true,
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T10:00:00.000Z"
}

Perbarui Webhook

PUT /webhooks/{id}

Perbarui satu atau lebih properti webhook yang ada. Semua field body bersifat opsional — hanya field yang Anda sediakan yang akan diubah. Gunakan isActive: false untuk menjeda pengiriman tanpa menghapus webhook.

Path Parameters

Parameter	Tipe	Deskripsi
`id` wajib	string (uuid)	ID webhook untuk diperbarui.

Body Request

Parameter	Tipe	Deskripsi
`url`	string (uri)	URL tujuan baru. Harus dimulai dengan `https://`.
`description`	string	Label yang dapat dibaca manusia yang diperbarui.
`events`	string[]	Menggantikan daftar lengkap tipe event yang dilanggani. Teruskan array kosong untuk berlangganan semua event.
`isActive`	boolean	Tetapkan ke `false` untuk menjeda pengiriman, atau `true` untuk melanjutkan.

Contoh Request

javascript

const res = await fetch(
  `https://api.agentsend.io/webhooks/${webhookId}`,
  {
    method: "PUT",
    headers: {
      "x-api-key": process.env.AGENTSEND_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      events: ["message.received", "message.delivered", "message.bounced"],
      isActive: true,
    }),
  }
);

const updated = await res.json();
console.log(updated.events); // updated event list

Respons — 200 OK

Mengembalikan objek Webhook yang diperbarui.

json

{
  "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "url": "https://your-app.com/webhooks/agentsend",
  "description": "Production inbound handler",
  "events": ["message.received", "message.delivered", "message.bounced"],
  "isActive": true,
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T12:34:00.000Z"
}

Hapus Webhook

DELETE /webhooks/{id}

Menghapus webhook secara permanen. Semua pengiriman event masa depan ke endpoint tersebut akan berhenti segera. Log pengiriman yang terkait dengan webhook disimpan untuk tujuan audit.

⚠

Tindakan ini tidak dapat dibatalkan. Jika Anda ingin menghentikan pengiriman sementara, gunakan PUT /webhooks/{id} dengan isActive: false.

Path Parameters

Parameter	Tipe	Deskripsi
`id` wajib	string (uuid)	ID webhook yang akan dihapus.

Contoh Request

javascript

await fetch(
  `https://api.agentsend.io/webhooks/${webhookId}`,
  {
    method: "DELETE",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
); // 204 No Content

Respons — 204 No Content

Mengembalikan body kosong saat sukses.

Tipe Event

Tipe event berikut dapat diteruskan ke events saat membuat atau memperbarui webhook. Hilangkan field events sepenuhnya (atau teruskan array kosong) untuk menerima semua event.

Event	Deskripsi
`domain.verified`	Domain kustom telah lulus verifikasi DNS dan siap digunakan.
`message.received`	Email masuk telah tiba di salah satu kotak masuk Anda.
`message.sent`	Pesan keluar diterima oleh server email penerima.
`message.delivered`	Pengiriman ke kotak surat penerima dikonfirmasi (jika didukung).
`message.bounced`	Hard bounce diterima — alamat tidak ada atau menolak pengiriman.
`message.complained`	Penerima menandai pesan sebagai spam.

💡

Untuk melihat bentuk payload lengkap untuk setiap tipe event, kunjungi panduan konseptual Webhooks.

← Sebelumnya API: Utas Selanjutnya → API: Domain