Incoming Webhooks

수신 웹훅

외부 서비스에서 notii 채팅방으로 메시지를 보낼 때 사용합니다. 채팅방에서 만든 웹훅 주소와 시크릿만 있으면 주문, 장애, 배포 같은 알림을 바로 보낼 수 있습니다.

POST/api/webhooks/in/{webhookId}

사용 가능

인증

웹훅 시크릿은 비밀번호처럼 보관해주세요. 아래 방식 중 하나로 보낼 수 있고, 헤더 설정이 가능한 서비스라면 Authorization 방식을 권장합니다.

방식	예시	용도
Authorization	`Bearer {secret}`	권장 방식
X-Webhook-Secret	`{secret}`	헤더 대안
Query	`?s={secret}`	헤더 설정이 어려운 도구 호환용

본문

처음 연동할 때는 text에 문자로 보내는 방식을 권장합니다. title은 선택값이고, 따로 보내지 않을 때는 text 첫 줄을 제목처럼 써도 됩니다.

필드	값 형태	필수 여부	설명
text	문자 또는 JSON 객체	권장	notii에 보낼 메시지 내용입니다. 처음 연동할 때는 문자로 보내는 방식을 권장합니다.
title	문자	선택	메시지 상단에 굵게 표시할 제목입니다. 보내지 않아도 text 첫 줄을 제목처럼 쓸 수 있습니다.
username	문자	선택	메시지의 작성자명으로 표시됩니다.
icon_url	문자	선택	작성자명 옆에 표시할 아이콘 이미지 주소입니다. https 공개 이미지만 사용할 수 있습니다.
content / message / body	문자 또는 JSON 객체	호환	기존 도구가 message 안에 content/text/body를 담아 보내는 경우를 위한 호환 필드입니다. 새 연동은 text 사용을 권장합니다.

예제

서버나 자동화 도구에서 그대로 참고할 수 있는 기본 예제입니다.

bash

curl -X POST "https://notii.team/api/webhooks/in/{webhookId}" \
  -H "Authorization: Bearer {secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "새 주문이 들어왔습니다.",
    "title": "주문 알림",
    "username": "쇼핑몰 봇",
    "icon_url": "https://example.com/icon.png"
  }'

await fetch("https://notii.team/api/webhooks/in/{webhookId}", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {secret}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "새 주문이 들어왔습니다.",
    title: "주문 알림",
    username: "쇼핑몰 봇",
    icon_url: "https://example.com/icon.png",
  }),
});

응답

ok가 true이면 notii에 메시지가 만들어진 상태입니다.

json

{
  "ok": true,
  "message_id": "4d9b6c64-7f2d-4c8a-8f0d-1c8a0f6f7b31"
}

제한

요청 빈도

웹훅 하나당 분당 60회까지 허용합니다.

본문 크기

최종 메시지 본문은 UTF-8 기준 16KB까지 저장합니다.

이미지 URL

icon_url은 https 공개 주소만 표시합니다.

에러

코드	이름	설명
400	잘못된 요청	webhookId 형식 오류, 본문 없음 등 요청 값이 올바르지 않습니다.
401	인증 실패	시크릿이 없거나 일치하지 않습니다.
404	찾을 수 없음	웹훅이나 연결된 채팅방을 찾을 수 없습니다.
410	사용 불가	채팅방이 휴지통에 있거나 팀이 삭제 예정 상태입니다.
413	본문 초과	최종 메시지 본문이 16KB를 넘었습니다.
429	요청 제한	웹훅당 분당 60회 제한을 넘었습니다.
500	서버 오류	notii 서버 설정 또는 저장 과정에서 문제가 생겼습니다.