수신 웹훅

수신 웹훅은 CI 파이프라인, 모니터링 도구, 사내 스크립트 같은 외부 도구가 HTTP 요청 한 번으로 채널에 메시지를 올리는 주소입니다. 이 문서는 요청을 어떻게 보내고, 어떤 응답이 오고, 무엇이 제한되는지 설명합니다. 본문에 쓸 수 있는 서식과 토큰은 표현 레퍼런스에, 복사해서 바로 쓸 수 있는 예시는 예제에 있습니다. 외부 도구가 같은 URL 과 시크릿으로 채널 대화를 읽어 가는 방법은 채널 읽기에 있습니다.

발급하기

채널 관리자가 채널 화면에서 발급합니다. 한 채널에 웹훅을 여러 개 만들 수 있으니 도구마다 따로 발급하면 어느 도구가 보낸 메시지인지 채널에서 바로 구분됩니다.

1. 채널 메뉴에서 채널 설정을 눌러 채널 편집 창을 엽니다. 아래쪽 웹훅 버튼을 누르면 웹훅 관리하기 창이 열립니다.

2. + 발급하기를 누르고 웹훅 프로필 표시에 채널에 보일 이름을 적습니다. 이름은 같은 채널 안에서 겹치면 안 됩니다. 프로필 사진은 선택이고, 메시지는 이 이름과 사진으로 올라갑니다.

3. 외부 도구가 이 채널의 대화도 읽어야 하면 채널 대화 읽기 허용을 켭니다. 기본은 꺼져 있고, 켜면 같은 URL 과 시크릿으로 채널 읽기를 할 수 있습니다. 발급한 뒤에도 바꿀 수 있습니다.

4. 저장을 누르면 URL, 시크릿, 그리고 붙여 넣어 바로 시험할 수 있는 curl 명령(보내보기)이 나옵니다.

발급이 끝나면 두 가지 값을 받습니다.

self-hosted 로 설치했다면 https://collabops.ai 자리에 설치한 서버 주소가 들어갑니다. 발급 화면에 보이는 URL 을 그대로 쓰면 됩니다.

켜기 · 끄기 · 이름 변경 · 삭제

웹훅 관리하기 창의 카드마다 켜기/끄기 스위치와 ⋯ 메뉴가 있습니다. ⋯ 메뉴에서 전송 기록, 채널 대화 읽기 허용, 이름 변경, 삭제를 고릅니다. 전송 기록은 채널 멤버 누구나 볼 수 있고, 나머지는 채널 관리자만 바꿀 수 있습니다.

요청 형식

curl -X POST "https://collabops.ai/api/v2/integration/webhook/<토큰>" \
  -H "Authorization: Bearer <시크릿>" \
  -H "Content-Type: application/json" \
  -d '{"text": "**배포 완료** `web` 0.4.2"}'

본문 — text 와 blocks

본문은 두 형식 중 정확히 하나를 씁니다. text 와 blocks 를 함께 넣거나 둘 다 빼면 422 입니다.

text 형식

blocks 형식

블록 종류와 모양은 표현 레퍼런스에 있습니다.

응답

요청을 받으면 게시를 기다리지 않고 바로 202 Accepted 를 돌려줍니다. 채널 게시는 그 뒤에 비동기로 이루어집니다.

{"delivery_id": 1234, "deduped": false}

오류 응답

실패하면 아래 모양의 JSON 이 옵니다. error.title 에 거절 사유가, error.request_id 에 문의할 때 알려 줄 추적 번호가 들어 있습니다. 같은 추적 번호가 X-Request-Id 응답 헤더에도 실립니다.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "title": "요청 형식이 올바르지 않습니다: exactly one of text or blocks is required",
    "request_id": "3f1c9a52-8e0b-4c1d-9f7a-2b6e4d8c1a90",
    "upstream_status": 422
  }
}

상한

블록 수는 변환된 뒤의 블록으로 셉니다. text 형식도 마크다운이 블록으로 바뀐 뒤의 개수입니다. 문단, 제목, 목록 항목은 하나가 블록 하나이고, 표는 셀 하나가 블록 하나입니다. 3열 10행 표는 그것만으로 30블록입니다. 공백뿐인 text 처럼 블록이 하나도 나오지 않는 본문도 422 로 거절됩니다.

긴 보고는 한 메시지에 몰아넣지 말고 스레드로 나눠 보내세요.

중복 방지

네트워크 오류로 응답을 못 받으면 발신 도구는 같은 요청을 다시 보내게 됩니다. Idempotency-Key 헤더에 알림마다 고유한 값을 넣어 두면 같은 키로 다시 와도 채널에는 한 번만 올라갑니다. 두 번째 응답은 deduped: true 와 처음 받은 delivery_id 를 돌려줍니다.

키를 넣지 않으면 요청마다 새 메시지가 됩니다. 커밋 SHA 와 이벤트 종류를 이은 deploy-3f9c2a71-success 처럼 같은 알림이면 늘 같은 값이 나오도록 만드세요. 401·422 처럼 거절된 요청은 키를 기억하지 않으므로, 본문을 고쳐 같은 키로 다시 보내면 정상적으로 처리됩니다.

스레드로 이어 보내기

응답으로 받은 delivery_id 를 다음 요청의 parent_delivery_id 에 넣으면 그 메시지의 답글로 올라갑니다. 채팅 내부의 메시지 번호는 몰라도 됩니다.

전송 결과 확인

웹훅 관리하기 창의 카드마다 마지막 수신 상태가 보이고, ⋯ 메뉴의 전송 기록에서 요청 한 건 한 건의 결과를 최신순으로 볼 수 있습니다. 한 건마다 받은 시각, 상태, 본문 형식(텍스트·블록), 스레드 답글 여부가 나옵니다. 게시된 건은 메시지 보기로 채널의 그 메시지를 열 수 있습니다. 거절된 건에는 error.title 의 콜론 뒤에 붙는 것과 같은 영문 사유가 보이고, 본문 검증에 실패한 건은 원문 보기로 보낸 JSON 을 확인할 수 있습니다.

웹훅을 찾지 못한 404, 1 MiB 를 넘은 413, 일시적인 5xx 는 기록되지 않으므로 발신 쪽 로그에서 응답 코드를 확인하세요.