본문으로 건너뛰기

인바운드 웹훅 설정

외부 메신저 공급사(Kakao·LINE 등)가 제로톡으로 메시지를 보낼 때 쓰는 수신 URL을 조회하는 API입니다. 공급사 콘솔에 등록한 URL이 제로톡에 발급된 URL과 같은지 대조할 때 씁니다.

목록 조회​

GET /inbound-webhook-configs — 워크스페이스에 연결된 공급사 인바운드 웹훅 설정 목록을 cursor pagination으로 조회합니다.

  • Scope: inbound-webhook-configs:read
  • 쿼리: limit(기본 50, 1~100), cursor(이전 응답의 meta.next_cursor 값)
  • 최신순(created_at 내림차순)으로 정렬됩니다.

범위를 벗어난 limit은 자동 보정 없이 400 INVALID_QUERY로 거부합니다. 발급 후 24시간이 지난 cursor도 같은 오류를 반환합니다. 자세한 규칙은 페이지네이션을 참고하세요.

이 목록은 공급사로 필터링하지 않고 워크스페이스의 연동을 모두 반환합니다. GET /integrations와 같은 연동에 webhook_url·icon_url이 추가된 형태입니다. 다만 /integrations는 음성 기능이 꺼진 워크스페이스의 voice 연동을 제외하고, 이 목록은 제외하지 않습니다. 인바운드 웹훅 경로가 없는 공급사(web·email)의 행도 포함되며, 이 경우 webhook_url 키는 생략됩니다.

아래 요청은 연동 50건의 웹훅 설정을 조회합니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/inbound-webhook-configs?limit=50" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "9f8e7d6c-...",
      "name": "카카오 채널 상담",
      "provider": "kakao",
      "status": "active",
      "webhook_url": "https://api.talk.zeroworks.ai/webhooks/kakao/abc123...",
      "icon_url": "https://cdn.zeroworks.ai/icons/kakao.png",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": false }
}

has_more가 true이면 응답의 meta.next_cursor(예: "eyJ...")를 다음 요청의 ?cursor=로 전달해 다음 페이지를 조회합니다. 마지막 페이지에서는 next_cursor가 생략됩니다.

필드​

필드타입설명
idstring연동 UUID
namestring사용자가 지정한 연동 이름
providerstring연동 공급사 (provider 값 참조)
statusstring연동 상태 (아래 값 집합 참조)
webhook_urlstring공급사 콘솔에 등록해야 할 수신 URL. 값이 없으면 키가 생략됩니다
icon_urlstring연동 아이콘 URL. 값이 없으면 키가 생략됩니다
created_at·updated_atstringRFC 3339 시각

webhook_url·icon_url은 값이 없으면 null이 아니라 응답 객체에서 키가 생략됩니다 ("key" in obj로 판별).

값 집합​

status는 데이터베이스 제약으로 정해진 닫힌 집합이므로 아래 값 외에는 반환되지 않습니다.

필드값 집합
statusactive · inactive · error · pending · awaiting_setup · awaiting_activation

provider 값과 각 값의 연동이 생기는 경로는 연동 — provider 값과 같습니다. voice 행의 음성 기능 조건만 이 목록에 적용되지 않습니다(위 목록 조회 설명). 모르는 provider 값을 받았을 때의 처리는 연동 — 모르는 provider 값 때문에 응답 처리가 실패할 때를 따르세요.

노출되지 않는 값​

webhook_url은 공급사 콘솔에 등록해야 할 수신 URL을 그대로 노출합니다. 고객이 등록한 URL이 맞는지 대조할 수 있도록 의도적으로 공개하며, 모든 인바운드 요청은 HMAC 서명으로 검증하므로 URL만으로는 위조 전송을 할 수 없습니다.

서명 검증에 쓰는 signing_secret(및 webhook token, 공급사 자격증명, config)은 조회 단계에서 아예 읽지 않으므로 응답에 포함되지 않습니다.