주소록 웹훅은 주소록에서 이벤트가 발생했을 때 사용자의 서버로 알림을 보내주는 기능입니다. 사용자는 어떤 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":"호열"}
]
}