웹훅

실시간 이벤트 알림을 받기 위해 HTTP 엔드포인트를 등록합니다. 웹훅 구독 전반의 전송 로그를 조회하고 활동을 모니터링하세요.

ⓘ

All requests require the x-api-key header. The base URL for every endpoint is https://api.agentsend.io.

Webhook 객체

웹훅을 반환하는 모든 엔드포인트는 이 형식을 반환합니다. secret 필드는 POST /webhooks의 응답에만 포함됩니다 — 다시 가져올 수 없으므로 안전하게 저장하세요.

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

필드	타입	설명
`id`	string (uuid)	웹훅의 고유 식별자.
`url`	string (uri)	AgentSend가 이벤트를 전달하는 HTTPS 엔드포인트.
`description`	string \| null	웹훅의 선택적 사람이 읽을 수 있는 레이블.
`events`	string[] \| null	구독 이벤트 타입 배열. `null` 또는 빈 배열은 모든 이벤트가 전달됨을 의미합니다.
`isActive`	boolean	웹훅이 현재 이벤트를 수신 중인지 여부.
`createdAt`	string (ISO 8601)	웹훅이 생성된 시각.
`updatedAt`	string (ISO 8601)	웹훅이 마지막으로 업데이트된 시각.

웹훅 만들기

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.

요청 본문

파라미터	타입	설명
`url` 필수	string (uri)	AgentSend가 이벤트를 POST할 HTTPS URL. `https://`로 시작하는 유효한 URI여야 합니다.
`description`	string	대시보드 및 로그에서 이 웹훅을 식별하는 사람이 읽을 수 있는 레이블.
`events`	string[]	구독할 이벤트 타입 목록. 모든 이벤트를 받으려면 생략하거나 빈 배열을 전달하세요. 유효한 값: `domain.verified`, `message.received`, `message.sent`, `message.delivered`, `message.bounced`, `message.complained`.

요청 예시

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

Response — 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은 생성 시에만 반환됩니다. 안전한 환경 변수에 즉시 저장하세요 — API를 통해 다시 가져올 수 없습니다.

웹훅 목록

GET /webhooks

계정에 등록된 모든 웹훅을 반환합니다. 목록이나 조회 응답에는 시크릿이 포함되지 않습니다.

요청 예시

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

Response — 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"
    }
  ]
}

이벤트 카탈로그 조회

GET /webhooks/catalog

웹훅이 구독할 수 있는 이벤트 타입의 전체 목록을 이름 및 설명과 함께 반환합니다. 이벤트 선택기 UI를 채우거나 런타임에 이벤트 이름을 검증하는 데 사용하세요.

요청 예시

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

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

전송 로그 목록

GET /webhooks/logs

개별 웹훅 전송 시도 목록을 최신순으로 반환합니다. 실패한 전송을 디버깅하고, 페이로드를 검사하고, 엔드포인트의 응답 코드를 검토하는 데 사용하세요.

쿼리 파라미터

파라미터	타입	설명
`webhookId`	string (uuid)	특정 웹훅으로 로그를 필터링합니다. 생략하면 모든 웹훅의 로그가 반환됩니다.
`status`	enum	전송 결과로 필터링. `success` 또는 `failed` 중 하나.
`event`	string	이벤트 타입으로 필터링 (예: `message.received`).
`limit`	integer	반환할 최대 로그 항목 수. 기본값 `20`.
`hours`	integer	시간 단위 조회 창. 기본값 `168` (7일).

요청 예시

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

Response — 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"
    }
  ]
}

활동 조회

GET /webhooks/activity

하나 또는 모든 웹훅에 대한 집계 전송 활동(시간 경과에 따른 성공 및 실패 카운트)을 반환합니다. 모니터링 대시보드에 차트를 렌더링하는 데 유용합니다.

쿼리 파라미터

파라미터	타입	설명
`webhookId`	string (uuid)	특정 웹훅으로 활동을 범위 지정합니다. 생략하면 모든 웹훅의 활동이 반환됩니다.
`hours`	integer	시간 단위 조회 창. 기본값 `6`.

요청 예시

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

Response — 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 }
  ]
}

웹훅 조회

GET /webhooks/{id}

ID로 단일 웹훅을 가져옵니다. 생성 후에는 시크릿이 반환되지 않습니다.

경로 파라미터

파라미터	타입	설명
`id` 필수	string (uuid)	가져올 웹훅의 ID.

요청 예시

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

Response — 200 OK

단일 Webhook 객체를 반환합니다 (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"
}

웹훅 업데이트

PUT /webhooks/{id}

기존 웹훅의 하나 이상의 속성을 업데이트합니다. 모든 본문 필드는 선택 사항입니다 — 제공한 필드만 변경됩니다. 웹훅을 삭제하지 않고 전송을 일시 중지하려면 isActive: false를 사용하세요.

경로 파라미터

파라미터	타입	설명
`id` 필수	string (uuid)	업데이트할 웹훅의 ID.

요청 본문

파라미터	타입	설명
`url`	string (uri)	새 대상 URL. `https://`로 시작해야 합니다.
`description`	string	업데이트된 사람이 읽을 수 있는 레이블.
`events`	string[]	구독한 이벤트 타입의 전체 목록을 대체합니다. 모든 이벤트를 구독하려면 빈 배열을 전달하세요.
`isActive`	boolean	전송을 일시 중지하려면 `false`, 재개하려면 `true`로 설정합니다.

요청 예시

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

Response — 200 OK

업데이트된 Webhook 객체를 반환합니다.

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

웹훅 삭제

DELETE /webhooks/{id}

웹훅을 영구적으로 삭제합니다. 해당 엔드포인트로의 향후 이벤트 전송이 즉시 중단됩니다. 웹훅과 관련된 전송 로그는 감사 목적으로 유지됩니다.

⚠

이 작업은 취소할 수 없습니다. 일시적으로 전송을 중지하려면 isActive: false로 PUT /webhooks/{id}를 사용하세요.

경로 파라미터

파라미터	타입	설명
`id` 필수	string (uuid)	삭제할 웹훅의 ID.

요청 예시

javascript

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

Response — 204 No Content

성공 시 빈 본문을 반환합니다.

이벤트 타입

웹훅을 생성하거나 업데이트할 때 다음 이벤트 타입을 events에 전달할 수 있습니다. 모든 이벤트를 받으려면 events 필드를 완전히 생략하거나 빈 배열을 전달하세요.

이벤트	설명
`domain.verified`	커스텀 도메인이 DNS 검증을 통과하여 사용 준비가 되었습니다.
`message.received`	수신 이메일이 수신함 중 하나에 도착했습니다.
`message.sent`	발신 메시지가 수신자 메일 서버에 의해 수락되었습니다.
`message.delivered`	수신자 메일함으로의 전송이 확인되었습니다 (지원되는 경우).
`message.bounced`	하드 바운스를 받았습니다 — 주소가 존재하지 않거나 전송을 거부했습니다.
`message.complained`	수신자가 메시지를 스팸으로 표시했습니다.

💡

각 이벤트 타입의 전체 페이로드 형식을 보려면 웹훅 개념 가이드를 방문하세요.

← 이전 API: 스레드 다음 → API: 도메인