채널 수신 웹훅

수명 주기

1. CREATE

   생성

   대상 채널의 수신 웹훅 화면에서 출처를 식별할 이름을 입력합니다. 조직 소유자·관리자 또는 채널 소유자만 관리할 수 있고, 보관된 채널에는 새 웹훅을 만들 수 없습니다.

2. STORE

   보관

   전체 비밀 URL은 생성 또는 회전 직후 한 번만 표시됩니다. 비밀 관리 도구에 저장하고 최소한의 발신 시스템에만 전달하세요.

3. ROTATE

   회전

   URL이 노출됐거나 담당 시스템이 바뀌면 회전합니다. 기존 URL은 즉시 404로 바뀌므로 새 URL을 발신 시스템에 바로 적용하고 시험 요청을 보내세요.

4. REVOKE

   폐기

   더 이상 사용하지 않으면 폐기합니다. 폐기는 즉시 적용되고 되돌릴 수 없으므로 다시 필요하면 새 웹훅을 만드세요.

엔드포인트

생성 화면에서 받은 정확한 URL을 사용하세요. webhook_id와 secret을 따로 조합하거나 Authorization 헤더를 추가할 필요가 없습니다.

POST https://briar-api.wbai.workers.dev/hooks/channels/{webhook_id}/{secret}

JSON 스키마

본문은 application/json이어야 하며 text 또는 blocks 중 하나 이상이 필요합니다. 아래 필드 외의 값은 허용되지 않습니다.

선택 헤더

Idempotency-Key 헤더도 공백 제거 후 1~200자입니다. eventId 대신 사용할 수 있으며 두 값을 함께 보낼 때는 반드시 같아야 합니다.

실행 가능한 curl 예제

첫 줄의 예시 URL 전체를 Briar가 한 번 표시한 실제 비밀 URL로 바꾼 뒤 실행하세요.

export BRIAR_WEBHOOK_URL='https://briar-api.wbai.workers.dev/hooks/channels/{webhook_id}/{secret}'

curl --fail-with-body \
  --request POST \
  --url "$BRIAR_WEBHOOK_URL" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: deploy-2026-08-12-001' \
  --data '{
    "text": "Production deployment completed.",
    "blocks": [
      {"type":"header","text":{"type":"plain_text","text":"배포 완료"}},
      {"type":"section","text":{"type":"mrkdwn","text":"*production*에 `v42`가 배포되었습니다."}},
      {"type":"divider"},
      {"type":"markdown","text":"- [x] Health checks\n- [ ] Monitor metrics"}
    ]
  }'

새 메시지 응답 · 201 Created

{
  "message": {
    "id": "…",
    "body": "Production deployment completed.",
    "blocks": [
      { "type": "header", "text": { "type": "plain_text", "text": "배포 완료" } },
      { "type": "section", "text": { "type": "mrkdwn", "text": "*production*에 `v42`가 배포되었습니다." } },
      { "type": "divider" },
      { "type": "markdown", "text": "- [x] Health checks\n- [ ] Monitor metrics" }
    ],
    "author": {
      "type": "webhook",
      "id": "…",
      "name": "Deploy alerts"
    }
  },
  "duplicate": false
}

중복 방지와 안전한 재시도

• 배포 ID, 모니터링 이벤트 ID처럼 발신 시스템에서 안정적으로 유지되는 값을 키로 사용하세요.
• 같은 웹훅과 같은 키로 다시 요청하면 새 메시지를 만들지 않고 최초 메시지를 200 OK와 duplicate: true로 반환합니다.
• 중복 요청의 text나 blocks가 달라도 최초 메시지는 바뀌지 않습니다. 같은 논리적 이벤트에는 같은 내용과 같은 키를 보내세요.
• 키를 생략하면 모든 요청이 새 메시지를 만듭니다. 네트워크 재시도가 가능한 연동에서는 키 사용을 권장합니다.

제한 조건

요청 방식

POST만 지원

본문 형식

application/json

본문 크기

최대 65,536바이트(64KiB)

메시지 내용

text 1~10,000자, blocks 1~50개, markdown 블록 합계 최대 12,000자

중복 방지 키

eventId 또는 Idempotency-Key 1~200자

요청 빈도

웹훅별 60초에 최대 60회

비밀 URL과 Content-Type 검사를 통과한 요청은 JSON이나 필드 검증에 실패하더라도 요청 빈도에 포함됩니다.

오류와 복구