Quire 웹훅 설정 가이드: 단계별로 따라 하기

최종 업데이트: 2026년 7월 24일

앱들이 서로 자동으로 대화할 수 있다면 얼마나 좋을까 생각해 본 적 있나요? 웹훅이 바로 그런 일을 해줍니다! 웹훅은 Quire 프로젝트에서 무슨 일이 일어나는 순간 서버에 알려주는 메신저라고 생각하면 됩니다. 새 업무가 생성되든, 누군가 담당자를 변경하든, 업무를 완료 처리하든 상관없이 말이죠.

이 가이드에서는 웹훅을 설정해 애플리케이션이 Quire와 계속 동기화되도록 하는 방법을 안내합니다. 손가락 하나 까딱하지 않아도 됩니다.

Quire 웹훅은 어떻게 시작하나요?

1단계: Quire 앱 만들기

가장 먼저 필요한 건 Quire 앱입니다. 아직 만들지 않았다면 Quire API로 Quire 앱 만들기 가이드를 참고해 하나씩 따라 해보세요.

2단계: 업데이트를 보낼 곳을 Quire에 알려주기

이제 Quire 개발자 앱 포털에서 웹훅 엔드포인트를 설정할 차례입니다. 이는 단순히 Quire가 알림을 보내길 원하는 웹 주소로, http://myserver/hookhandler 같은 형태입니다.

Quire에게 우편 주소를 알려줘서 소식을 어디로 전달해야 할지 알게 해주는 것이라고 생각하면 됩니다.

3단계: 업데이트 구독하기

마지막 설정 단계는 어떤 프로젝트나 업무를 팔로우할지 Quire에게 알려주는 것입니다. Quire API를 사용해 앱을 "팔로워"로 추가하면 됩니다.

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app"]}' \
  https://quire.io/api/project/projectAOid

중요: 이 단계 전에 웹훅 URL을 반드시 설정해 두어야 합니다. 설정하지 않으면 앱을 팔로워로 추가해도 동작하지 않습니다.

더 이상 업데이트가 필요 없을 때는 팔로워 목록에서 앱을 제거하기만 하면 됩니다. 정말 간단하죠!

더 자세한 내용은 API 레퍼런스의 OID로 프로젝트 업데이트하기를 참고하세요.

웹훅은 내부적으로 어떻게 동작하나요?

무엇을 받게 되나요

설정이 끝나면 Quire는 팔로우 중인 프로젝트에서 무슨 일이 생길 때마다 알림을 보내기 시작합니다. 이 알림은 세부 정보가 담긴 깔끔한 JSON 패키지 형태의 POST 요청으로 전달됩니다.

{
  "type": "notification",
  "secret": "your-app-secret",
  "data": {
    "type": 0, 
    "when": "2019-09-30T08:20:12.000Z",
    "what": {
      "oid": "YxjapXXRCOYxoaiCT4tT3OQm", 
      "id": 101,
      "name": "Brand new start"
    },
    "user": {
      "oid": "1AbDEFed2A5031BEDDweqmde",
      "id": "john.doer",
      "name": "John Doer"
    },
    "message": "<a href=\"https://quire.io/u/john.doer\">John Doer</a> added <a href=\"https://quire.io/w/MyProjects/101\">Brand new start</a>",
    "text": "John Doer added Brand new start",
    "url": "https://quire.io/w/MyProjects/101"
  } 
}

보안이 최우선: 출처 확인하기

각 웹훅에는 앱의 시크릿 키가 포함되어 있습니다. 이는 메시지가 실제로 Quire에서 온 것이며 누군가 우리인 척 위장한 것이 아님을 확인하는 방법입니다. 어떤 데이터든 처리하기 전에 반드시 이를 확인하세요!

다양한 이벤트에 대응하기

프로젝트에서는 여러 가지 일이 일어나며, 그때마다 각기 다르게 처리하고 싶을 것입니다. 발생한 이벤트에 따라 대응하는 간단한 예시는 다음과 같습니다.

switch(json["data"]["type"]) {
  case 0:
    // new task added
    log("New task: " + json["data"]["what"]["name"]);
    break;
  case 1:
    // task removed
    log(json["data"]["user"]["name"] + " deleted " + json["data"]["what"]["name"]);
    break;
}

Quire는 어떤 이벤트 유형을 보내나요?

Quire는 다양한 활동에 대해 알림을 보낼 수 있습니다. 가장 흔한 유형은 다음과 같습니다.

전체 목록이 궁금하다면 활동 유형 문서에서 Quire가 알려줄 수 있는 모든 것을 확인해 보세요.

메시지를 받았다고 Quire에 알려주기

웹훅이 알림을 수신하면, 성공 상태 코드(200~299 범위 아무거나)를 돌려보내기만 하면 됩니다. 이렇게 하면 Quire에게 "잘 받았어요, 고마워요!"라고 알려주는 셈입니다.

문제가 생겨서 다른 상태 코드를 돌려보내면 걱정할 필요 없이, Quire가 15분 후, 1시간 후, 마지막으로 1일 후에 알림을 다시 보내드립니다.

더 자세한 내용은 API 문서의 "응답 및 재시도"를 참고하세요.

여러 프로젝트에 걸친 웹훅은 어떻게 관리하나요?

같은 서버에서 여러 Quire 프로젝트를 다루고 있나요? 두 가지 유연한 방법을 소개합니다.

방법 1: 커스텀 라벨 사용하기

프로젝트 업데이트를 구독할 때 커스텀 라벨을 추가할 수 있습니다.

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app|handleProjectA"]}' \
  https://quire.io/api/project/projectAOid

Quire는 이 라벨을 모든 웹훅 알림에 포함시켜, 어느 프로젝트에서 보낸 알림인지 쉽게 구분할 수 있게 해줍니다.

{
  "type": "notification",
  "team": "handleProjectA",
  "data": {
    // event details...
  }
}

그러면 코드에서 알림을 다음과 같이 라우팅할 수 있습니다.

switch(json["data"]["type"]) {
  case 0:
    // new task added
    if (json["team"] == "handleProjectA") {
      log("ProjectA has a new task: " + json["data"]["what"]["name"]);
    }
    break;
}

방법 2: 서로 다른 경로 사용하기

각각을 분리해서 관리하고 싶다면, 프로젝트마다 고유한 경로를 설정하세요.

curl -H 'Authorization: Bearer {access_token}' -X PUT \
  -d '{"addFollowers":["app|/projectAUpdate"]}' \
  https://quire.io/api/project/projectAOid

이렇게 하면 Quire는 메인 엔드포인트의 서로 다른 서브패스(예: http://myserver/hookhandler/projectAUpdate)로 알림을 보내며, 각 프로젝트를 전용 핸들러로 개별 처리할 수 있습니다.

첫 웹훅까지 가장 빠른 길은?

이게 전부입니다! 이제 웹훅을 설정하고 애플리케이션을 Quire와 완벽하게 동기화하는 방법을 알게 되셨습니다. 전체 기술 문서는 API 레퍼런스의 웹훅 섹션에서 확인할 수 있습니다.

커스텀 서버가 아니라 AI 어시스턴트용으로 구축 중이신가요? 5분 만에 끝내는 Quire MCP 설정을 참고해 Claude, ChatGPT 등 어떤 AI 클라이언트와도 바로 연결해 보세요.

즐거운 개발 되세요!

자주 묻는 질문

Quire 웹훅이란 무엇인가요?

팔로우 중인 프로젝트에서 어떤 일이 발생하는 순간 Quire가 사용자가 지정한 URL로 자동 전송하는 HTTP 알림입니다. 폴링 없이도 앱이 계속 동기화 상태를 유지할 수 있습니다.

Quire에서 웹훅은 어떻게 설정하나요?

Quire 앱을 만들고, 개발자 앱 포털에서 엔드포인트 URL을 등록한 다음, API를 통해 앱을 프로젝트 팔로워로 추가하세요. 구독하기 전에 URL을 먼저 설정해야 하며, 그렇지 않으면 호출이 실패합니다.

웹훅 요청이 실제로 Quire에서 온 것인지 어떻게 확인하나요?

모든 페이로드에는 앱의 secret 필드가 포함되어 있습니다. 이를 저장된 시크릿과 비교해 일치하지 않는 요청은 거부하세요.

웹훅이 발생했을 때 서버가 다운되어 있으면 어떻게 되나요?

Quire는 15분 후, 1시간 후, 1일 후 이렇게 세 차례 재시도합니다. 페이로드를 수신하는 즉시 2xx 상태를 반환해 추가 재시도를 막으세요.

하나의 서버에서 여러 Quire 프로젝트의 웹훅을 어떻게 처리하나요?

구독 시 커스텀 라벨(예: app|handleProjectA)을 붙여 team 필드로 라우팅하거나, 웹훅 URL에 프로젝트마다 별도의 서브패스를 지정하면 됩니다.