Webhooks

{
  "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"
}

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

{
  "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"
}

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`);

{
  "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"
    }
  ]
}

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));

{
  "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."
    }
  ]
}

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));

{
  "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"
    }
  ]
}

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);

{
  "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 }
  ]
}

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);

{
  "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"
}

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

{
  "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"
}

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