주소록 웹훅은 주소록에서 이벤트가 발생했을 때 사용자의 서버로 알림을 보내주는 기능입니다. 사용자는 어떤 URL로 알림을 받을지, 어떤 내용의 알림을 받을지 설정할 수 있습니다. 알림은 POST Method를 사용하여 JSON 형태로 전달됩니다. 웹훅은 주소록 단위로 관리되며 하나의 주소록은 여러개의 웹훅을 가질 수 있습니다.

주소록 웹훅은 주소록 API와 함께 사용하면 더욱 강력한 기능이 됩니다 💪🏼

1. 웹훅 만들기

웹훅을 사용하려면 우선 스티비에서 웹훅을 만들어야 합니다. 웹훅은 주소록 단위로 관리되기 때문에 웹훅의 생성과 관리는 모두 주소록 > 웹훅에서 이루어집니다. 새로 만들기를 클릭하면 웹훅을 만들 수 있습니다.

웹훅을 만들기 위해 다음의 정보를 입력합니다.

  • 이름: 웹훅을 관리하기 위한 이름을 입력합니다.
  • URL: 이벤트 알림을 받을 URL을 입력합니다.
  • 알림을 받을 이벤트: 알림을 받을 이벤트를 선택합니다. 복수 선택이 가능합니다.

주소록 > 웹훅에서 생성된 웹훅을 확인하고, 웹훅을 활성화, 비활성화, 수정, 삭제할 수 있습니다.

웹훅에는 별도의 인증 과정이 없기 때문에, 인증이 필요한 경우 스티비의 웹훅 서버의 IP 주소로 인증 처리를 해야 합니다. 스티비의 웹훅 서버의 IP 주소는 다음과 같습니다.

  • 52.78.132.66

2. 이벤트 종류

웹훅에서 알림을 받을 수 있는 이벤트의 종류는 다음과 같습니다.

  • 구독: 주소록에 구독자가 추가됐습니다.
  • 구독자 정보 변경: 구독자의 정보(이름 등)가 변경됐습니다.
  • 수신거부: 구독자가 수신거부 상태로 변경됐습니다.
  • 수신거부 취소: 구독자의 수신거부가 취소됐습니다.
  • 자동삭제: 구독자가 자동삭제 상태로 변경됐습니다.
  • 완전삭제: 구독자가 완전삭제됐습니다.

모든 이벤트는 관리자 또는 API를 통해 발생하거나 구독자에 의해 발생했을 수 있습니다. 이에 대한 정보는 별도의 String으로 전달됩니다.

3. 이벤트 모델

웹훅 알림은 POST Method를 사용하여 JSON 형식으로 전달됩니다. 전달되는 이벤트 모델의 기본 구조는 다음과 같습니다.

id

주소록의 고유 아이디입니다.

action

발생한 이벤트의 종류입니다.

  • "SUBSCRIBED": 구독
  • "UPDATED": 구독자 정보 변경
  • “UNSUBSCRIBED”: 수신거부
  • “RESUBSCRIBED”: 수신거부 취소
  • “DELETED”: 자동삭제
  • “PURGED”: 완전삭제

eventOccuredBy

이벤트를 발생시킨 주체입니다.

  • “MANUAL”: 관리자 또는 API에 의해 발생
  • “SUBSCRIBER”: 구독자에 의해 발생

subscribers

구독자 정보를 담고 있습니다. Key-Value 배열 형식으로 구성됩니다. 주소록 > 사용자 정의 필드에 정의된 내용을 참조합니다.

  • Key: 사용자 정의 필드의 “태그”(email, name 등)
  • Value: Key에 해당하는 값구독, 구독자 정보 변경 이벤트 발생시에만 [사용자 정의 필드]에 정의된 내용이 포함되며, 나머지 이벤트에 대해서는 “email” 값만 표시됩니다.

4. 이벤트 예제

구독자가 구독 신청 양식을 통해 직접 구독한 경우, 다음과 같은 이벤트 알림이 전달됩니다.

{
    "id":"4617",
    "action":"SUBSCRIBED",
    "eventOccuredBy":"SUBSCRIBER",
    "subscribers": [
        {"email":"hoyeol@slowalk.co.kr", "name":"호열"}
    ]
}

구독자가 수신거부한 경우, 다음과 같은 이벤트 알림이 전달됩니다.

{
    "id":"4617",
    "action":"UNSUBSCRIBED",
    "eventOccuredBy":"SUBSCRIBER",
    "subscribers": [
        {"email":"hoyeol@slowalk.co.kr"}
    ]
}

스티비에서 관리자가 여러명의 구독자를 한 번에 추가한 경우, 다음과 같은 이벤트 알림이 전달됩니다.

{
    "id":"4617",
    "action":"SUBSCRIBED",
    "eventOccuredBy":"MANUAL",
    "subscribers": [
        {"email":"yunki@slowalk.co.kr", "name":"윤기"}
        {"email":"ej@slowalk.co.kr", "name":"은지"}
        {"email":"hakjin@slowalk.co.kr", "name":"학진"}
        {"email":"hoyeol@slowalk.co.kr", "name":"호열"}
    ]
}

답변을 찾으셨나요?