주소록 웹훅은 주소록에서 이벤트가 발생했을 때 사용자의 서버로 알림을 보내주는 기능입니다. 사용자는 어떤 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":"gildong@stibee.com", "name":"길동"}
]
}구독자가 수신거부한 경우, 다음과 같은 이벤트 알림이 전달됩니다.
{
"id":"4617",
"action":"UNSUBSCRIBED",
"eventOccuredBy":"SUBSCRIBER",
"subscribers": [
{"email":"gildong@stibee.com"}
]
}스티비에서 관리자가 여러명의 구독자를 한 번에 추가한 경우, 다음과 같은 이벤트 알림이 전달됩니다.
{
"id":"4617",
"action":"SUBSCRIBED",
"eventOccuredBy":"MANUAL",
"subscribers": [
{"email":"gildong@stibee.com", "name":"길동"}
{"email":"dooly@stibee.com", "name":"둘리"}
{"email":"doner@stibee.com", "name":"도우너"}
]
}