# 웹훅으로 푸시 알림함 기능 구성하기

{% hint style="info" %}
알림함이란 앱이나 웹서비스에서 수신하는 다양한 알림을 한 곳에 모아놓는 기능을 말합니다.\
사용자가 푸시 알림을 보지 못했거나 다시 보고 싶을때 알림함에 들어가 다시 확인할 수 있습니다.
{% endhint %}

핵클의 푸시 캠페인과 웹훅을 활용하여 쉽게 알림함 구현이 가능합니다.

### 들어가기 전에

{% hint style="warning" %}
웹훅 캠페인을 설정하기 이전에 발송된 푸시메시지는 알림함에 노출되지않습니다.
{% endhint %}

### $push\_send 이벤트 알아보기

이번 예제에서는 핵클에서 푸시 캠페인을 진행하면, 자동으로 수집되는 이벤트인 `$push_send` 를 활용합니다.

`$push_send` 이벤트는 푸시 메시지 발송이 요청될 때 발생합니다.\
즉, 푸시 메시지가 발송되는 이벤트를 트리거로 잡아 웹훅 캠페인을 발송하는 개념입니다.

#### $push\_send

`$push_send` 이벤트가 수집하는 이벤트 속성은 다음과 같습니다.

<table><thead><tr><th width="251.94140625">Field</th><th width="127.6875">Type</th><th>Description</th></tr></thead><tbody><tr><td>push_message_key</td><td>Long</td><td>푸시 메시지 캠페인의 키 값이 들어있습니다.</td></tr><tr><td>platform</td><td>String</td><td>푸시 메시지 발송 대상의 플랫폼 타입 입니다. (<code>ANDROID</code> 또는 <code>IOS</code>)</td></tr><tr><td>push_token</td><td>String</td><td>푸시 메시지 발송 대상의 푸시 토큰 입니다</td></tr><tr><td>title</td><td>String</td><td>고객에게 표시되는 푸시 메시지 타이틀입니다.</td></tr><tr><td>push_message_body</td><td>String</td><td>고객에게 표시되는 푸시 메시지 내용 부분입니다.</td></tr><tr><td>push_message_action_type</td><td>String</td><td><code>APP_OPEN</code> 또는 <code>DEEP_LINK</code> 값이 들어옵니다.</td></tr><tr><td>push_message_action_value</td><td>String</td><td>action_type 이 DEEP_LINK 인 경우 딥 링크 값이 들어갑니다.<br>아닌 경우 Empty String("") 입니다.</td></tr><tr><td>debug</td><td>Boolean</td><td>테스트 발송 여부입니다. (true 또는 false)</td></tr><tr><td>result</td><td>String</td><td>푸시 발송 요청 결과 코드입니다.</td></tr><tr><td>tag_keys</td><td>String</td><td>대시보드에서 설정한 태그 값입니다.</td></tr></tbody></table>

`$push_send` 이벤트에 result 속성 값을 통해 발송 성공 여부를 확인할 수 있습니다.\
발송 요청 결과 코드는 다음과 같습니다.

<table><thead><tr><th width="378.3046875">Name</th><th>Description</th></tr></thead><tbody><tr><td>SUCCESS</td><td>전송 성공 시</td></tr><tr><td>DEDUP</td><td>특정 캠페인의 중복 발송 제한에 걸린 경우</td></tr><tr><td>GLOBAL_FREQUENCY_CAPPED</td><td>전체 캠페인 발송 빈도 제한 설정으로 제한된 경우</td></tr><tr><td>NOT_FOUND_PUSH_PROVIDER_CREDENTIALS</td><td>푸시 제공자 인증 정보가 없는 경우</td></tr><tr><td>INVALID_PUSH_PROVIDER_CREDENTIALS</td><td>푸시 제공자 인증 정보가 유효하지 않은 경우</td></tr><tr><td>INVALID_PUSH_TOKEN</td><td>유효하지 않은 푸시 토큰인 경우</td></tr><tr><td>INTERNAL_ERROR</td><td>서버 오류 발생 시</td></tr></tbody></table>

#### 유저 식별자

$push\_send 이벤트는 발송 대상의 식별자 중 하나를 수집합니다.

<table><thead><tr><th width="126.7734375">Field</th><th width="162.4453125">Type</th><th>Description</th></tr></thead><tbody><tr><td>userId</td><td>String(nullable)</td><td>푸시 발송 대상 유저의 userId 식별자</td></tr><tr><td>deviceId</td><td>String(nullable)</td><td>푸시 발송 대상 유저의 deviceId 식별자</td></tr></tbody></table>

![](/files/Y57uNC55ZsLSQUkTxCWW)

### 웹훅 설정하기

아래 순서대로 설정하면 푸시 알림함을 구성할 수 있습니다.

{% stepper %}
{% step %}
**웹훅 캠페인 생성**

대시보드의 **웹훅** 메뉴 우측 상단에서 \*\*`+ 캠페인 만들기`\*\*를 클릭합니다.

원하는 캠페인 이름을 입력해 생성해주세요.

![](/files/0ZpGpJT6y2hnimTtBQ7h)

![](/files/L0uJ0FIuIOURQtyZhr37)
{% endstep %}

{% step %}
**요청 정보 설정**

**Method 설정**

Method 는 `POST` 로 설정합니다.

**Headers 및 Parameter 설정**

푸시 알림함 API 스펙에 맞춰 Headers 에 인증정보 등을 추가합니다.

여기서는 Authorization 헤더에 유저 속성의 `access-token` 을 활용한다고 가정합니다.

![](/files/pP8uevfiDZlSCJzg8nHd)

**Body 설정**

[Liquid 문법을 활용](https://shopify.github.io/liquid/)해 웹훅 Request Body 를 작성합니다.

앞서 살펴본 `$push_send` 이벤트 속성과 식별자를 그대로 활용합니다.

**Request Body**

```
{ 
 "identifiers":{
 	"userId": "{{identifiers["$userId"]}}",
 	"deviceId":"{{identifiers["$deviceId"]}}" 
 },
 "key": "{{event_properties["push_message_key"]}}", 
 "platform": "{{event_properties["platform_type"]}}", 
 "push_token": "{{event_properties["push_token"]}}",
 "title": "{{event_properties["push_message_title"]}}",
 "body": "{{event_properties["push_message_body"]}}",
 "actionType": "{{event_properties["push_message_action_type"]}}",
 "actionValue":"{{event_properties["push_message_action_value"]}}"
}
```

![](/files/8kdoFDnH3lmM2jvMyH6h)

개인화에 사용한 속성이나 식별자 값이 `null` 이면 `""` 로 치환됩니다.
{% endstep %}

{% step %}
**대상 설정**

**기본 설정 - 모든 푸시 캠페인**

모든 푸시 캠페인을 알림함에 노출하려면 대상으로 **모든 사용자**를 선택합니다.

![](/files/fpEz49DI9WFtRWiG3Maq)

**고급 설정 - 특정 푸시 캠페인**

특정 푸시 캠페인만 알림함에 노출하려면 푸시 캠페인의 대상 코호트와 일치하도록 웹훅 코호트를 설정합니다.

![](/files/uD8rhLuMvVUTsnuVw46V)

{% hint style="warning" %}
푸시 캠페인 대상과 웹훅 캠페인 대상은 꼭 맞춰주세요.

웹훅 캠페인 대상은 푸시 캠페인 대상과 같거나 더 넓어야 합니다.

가장 안전한 방법은 웹훅 캠페인 대상을 `모든 사용자`로 두는 것입니다.
{% endhint %}
{% endstep %}

{% step %}
**발송 설정**

웹훅 캠페인 설정을 완료하면 요약 내용을 확인할 수 있습니다.

`저장하기`를 누른 뒤 `발송설정`을 클릭합니다.

![](/files/8eHgSqJwuGmSCx4ANrXc)

발송 유형은 `이벤트 기반`으로 선택합니다.

시작 이벤트는 `$push_send` 로 설정합니다.

그 뒤 `필터 추가하기`를 눌러 아래 조건을 추가합니다.

| Key                | Value         | 설명                          |
| ------------------ | ------------- | --------------------------- |
| push\_message\_key | (푸시 캠페인의 키 값) | (선택) 특정 푸시 캠페인만 설정하고 싶은 경우  |
| result             | SUCCESS       | (추천) 전송 성공한 메세지만 보여주고 싶은 경우 |

**기본 설정 - 모든 푸시 캠페인**

모든 푸시 캠페인을 알림함에 노출하려면 `result=SUCCESS` 조건만 설정합니다.

![](/files/McbvpL4EkDIIsOWRPQKE)

**고급 설정 - 특정 푸시 캠페인**

특정 푸시 캠페인만 노출하려면 `result` 와 함께 `push_message_key` 도 추가합니다.

예를 들어 메시지 키 값이 `2` 인 푸시만 노출하려면 `push_message_key=2`, `result=SUCCESS` 로 설정합니다.

![](/files/ggSZjAMbfIWIk6e223WD)

이 웹훅 캠페인은 알림함 데이터 전송용입니다.

따라서 별도의 발송 제한은 보통 필요하지 않습니다.
{% endstep %}

{% step %}
**완료**

푸시 알림함을 위한 웹훅 구성이 끝났습니다.

이제 알림함 수신 API 를 구현하면 실제 알림함 기능을 완성할 수 있습니다.

![](/files/WbfPytelQwK96jRIaL0n)
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hackle.io/crm-marketing/webhook-guide/use-cases/webhook-push-inbox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.