Webhooks

Dapatkan notifikasi real-time saat event terjadi di akun AgentSend Anda — email baru diterima, pengiriman dikonfirmasi, bounce terdeteksi, dan lainnya.

Ikhtisar

Alih-alih polling API untuk memeriksa pesan baru, webhook memungkinkan AgentSend mengirim data event ke server Anda saat sesuatu terjadi. Daftarkan endpoint HTTPS dan AgentSend akan mengirim request POST dengan payload JSON setiap kali event yang dilanggani terpicu.

Webhook adalah cara yang direkomendasikan untuk membangun agen reaktif. Saat balasan tiba di kotak masuk agen Anda, aplikasi Anda menerima payload pesan lengkap dalam hitungan detik dan dapat segera bertindak.

Membuat Webhook

Daftarkan webhook baru dengan mengirim request POST ke /webhooks. Anda harus menyediakan field url; semua field lain opsional.

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://myapp.example.com/hooks/agentsend",
    description: "Production inbox events",
    events: ["message.received", "message.bounced"],
  }),
});

const webhook = await res.json();
console.log(webhook.id);     // wh_01j9...
console.log(webhook.secret); // whsec_... store this securely!

Tipe Event

Berlangganan event tertentu dengan meneruskan pengenal mereka di array events. Jika Anda menghilangkan array, AgentSend mengirimkan semua tipe event ke endpoint Anda.

Payload Webhook

Setiap pengiriman webhook adalah request POST dengan body Content-Type: application/json. Payload memiliki envelope yang konsisten terlepas dari tipe event.

{
  "id": "evt_01j9xkq7z8abc",
  "type": "message.received",
  "createdAt": "2026-04-16T10:23:45.000Z",
  "webhookId": "wh_01j9abc123",
  "data": {
    "id": "msg_01j9xkp4n5def",
    "inboxId": "inbox_01j8mq3r2t",
    "threadId": "thr_01j9xkp4m1ghi",
    "fromAddress": "alice@example.com",
    "fromName": "Alice Chen",
    "toAddresses": ["a1b2c3@agentsend.io"],
    "subject": "Re: Your proposal",
    "bodyText": "Looks great, let's move forward.",
    "bodyHtml": "<p>Looks great, let's move forward.</p>",
    "hasAttachments": false,
    "receivedAt": "2026-04-16T10:23:44.812Z"
  }
}

Memverifikasi Tanda Tangan

Setiap request webhook menyertakan header X-AgentSend-Signature. Ini adalah hash HMAC-SHA256 dari body request mentah, ditandatangani dengan secret webhook Anda. Selalu verifikasi tanda tangan ini sebelum memproses pengiriman untuk melindungi dari request palsu.

import crypto from "node:crypto";

app.post("/hooks/agentsend", express.raw({ type: "application/json" }), (req, res) => {
  const sig       = req.headers["x-agentsend-signature"];
  const secret    = process.env.AGENTSEND_WEBHOOK_SECRET;
  const expected  = crypto
    .createHmac("sha256", secret)
    .update(req.body) // raw Buffer — do NOT parse JSON first
    .digest("hex");

  if (!crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expected)
  )) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  // handle event.type …
  res.sendStatus(200);
});

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/hooks/agentsend", methods=["POST"])
def webhook():
    sig      = request.headers.get("X-AgentSend-Signature", "")
    secret   = os.environ["AGENTSEND_WEBHOOK_SECRET"].encode()
    expected = hmac.new(secret, request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(sig, expected):
        abort(401)

    event = request.get_json()
    # handle event["type"] …
    return "", 200

Kebijakan Retry

AgentSend menganggap pengiriman berhasil saat endpoint Anda merespons dengan kode status HTTP 2xx dalam 10 detik. Jika request timeout atau mengembalikan respons non-2xx, pengiriman dicoba ulang dengan back-off eksponensial:

Setelah 5 retry gagal (6 total percobaan), pengiriman ditandai sebagai failed dan tidak ada percobaan lebih lanjut. Anda dapat memeriksa pengiriman yang gagal di log pengiriman dan memutarnya ulang secara manual dari dasbor.

Mengelola Webhook

API webhook memungkinkan Anda menampilkan, memperbarui, dan menghapus endpoint terdaftar Anda.

Daftar webhook

Mengembalikan semua webhook yang terdaftar di akun Anda.

# GET /webhooks
curl https://api.agentsend.io/webhooks \
  -H "x-api-key: $AGENTSEND_API_KEY"

Memperbarui webhook

Ubah URL, deskripsi, atau tipe event yang dilanggani. Anda juga dapat memutar secret penandatanganan dengan meneruskan "rotateSecret": true — respons akan menyertakan secret baru.

# PUT /webhooks/{id}
curl -X PUT https://api.agentsend.io/webhooks/wh_01j9abc123 \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["message.received", "message.delivered", "message.bounced"]}'

Menghapus webhook

Menghapus webhook secara permanen. Pengiriman dalam proses masih dicoba sebelum penghapusan berlaku.

# DELETE /webhooks/{id}
curl -X DELETE https://api.agentsend.io/webhooks/wh_01j9abc123 \
  -H "x-api-key: $AGENTSEND_API_KEY"

Pemantauan aktivitas

Dapatkan ringkasan volume event baru-baru ini dan tingkat error untuk webhook tertentu.

# GET /webhooks/activity
curl "https://api.agentsend.io/webhooks/activity?webhookId=wh_01j9abc123" \
  -H "x-api-key: $AGENTSEND_API_KEY"

Log Pengiriman

Setiap percobaan pengiriman dicatat. Query endpoint log untuk memeriksa riwayat lengkap webhook, termasuk kode respons HTTP, body respons, dan waktu.

# Fetch failed deliveries for a webhook
curl "https://api.agentsend.io/webhooks/logs?webhookId=wh_01j9abc123&status=failed" \
  -H "x-api-key: $AGENTSEND_API_KEY"

Setiap entri log meliputi:

• id — ID unik percobaan pengiriman.
• eventId — ID event asal.
• eventType — misalnya message.received.
• status — success, failed, atau pending.
• httpStatus — Kode respons HTTP yang dikembalikan endpoint Anda.
• durationMs — Waktu round-trip dalam milidetik.
• attempt — Percobaan ke berapa (1 = pengiriman pertama).
• createdAt — Timestamp percobaan.