# 웹훅 설정

들어오는 JSON 페이로드에서 데이터를 추출하도록 웹훅 메시지 템플릿을 설정하는 방법을 알아보세요.

## 메시지 템플릿 문법

웹훅을 만들 때 들어오는 JSON 데이터를 알림으로 어떻게 변환할지 정하는 메시지 템플릿을 정의합니다.

### 기본 패턴

| 패턴 | 설명 |
|---------|-------------|
| `*` | JSON 페이로드 전체를 출력합니다 |
| `%field%` | 최상위 필드를 추출합니다 |
| `%object.field%` | 중첩된 필드를 추출합니다 |
| `%array.0%` | 배열의 첫 번째 요소를 가져옵니다 |
| `%array.0.field%` | 배열 요소의 필드를 가져옵니다 |
| `%%` | 리터럴 `%`입니다. `%`처럼 바로 뒤에 다른 `%cpu%%%`가 붙는 단어 앞에서만 필요합니다. `%`처럼 `90% on %host%` 뒤에 공백이 오면 그대로 유지됩니다 |

플레이스홀더에는 공백이 들어가지 않으므로, 일반 텍스트의 퍼센트 기호는 그대로 둡니다. 예를 들어 `CPU over 90% on %host%`는 `CPU over 90% on db-1`로 렌더링됩니다.

## 예제

### 예제 JSON 페이로드

다음과 같은 웹훅 페이로드가 들어온다고 가정해 보겠습니다:

```json
{
  "event": {
    "title": "New Order",
    "message": "A new order has been placed with ID 12345",
    "tags": ["order", "new"],
    "users": [
      {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
      {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
      {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
    ]
  }
}
```

### 템플릿 설정

**Full JSON**

```text
*
```

**Extracted Fields**

```text
Title: %event.title%
Message: %event.message%
Tags: %event.tags%
Users: %event.users.0%
First user: %event.users.0.first% %event.users.0.last%
```

### 출력 결과

```
Title: New Order
Message: A new order has been placed with ID 12345
Tags: ["order","new"]
Users: {"age":44,"first":"Dale","last":"Murphy","nets":["ig","fb","tw"]}
First user: Dale Murphy
```

## 자주 쓰는 연동

### GitHub 웹훅

```text
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%
```

### Sentry 오류 추적

알림 액션(이슈 알림)으로 사용하는 내부 연동의 경우:

```text
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%
```

이슈를 열 `view` 버튼을 `%data.event.web_url%`과 함께 추가하세요. 레거시 Webhooks 플러그인은 다른 페이로드를 보냅니다. 이 경우에는 `%project_name%: %event.title%`과 `%url%`을 사용하세요.

### Grafana 알림

```text
⚠️ %state%: %title%

%message%

Status: %status%
```

### Uptime Robot

```text
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%
```

## 고급 경로 문법

복잡한 JSON 추출에는 [GJSON Path Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)를 사용합니다.

### 유용한 패턴

| 패턴 | 설명 |
|---------|-------------|
| `%users.#%` | 배열 항목 수 |
| `%users.#.first%` | 모든 `first` 값의 배열 |
| `%users.@reverse%` | 배열 순서 뒤집기 |
| `%data.@pretty%` | JSON 보기 좋게 출력 |

> **Tip: 더 알아보기**
>
> 전체 문서: [GJSON Path Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## 우선순위 수준

들어오는 페이로드에 `level` 필드를 포함해 푸시 알림의 전달 방식을 제어할 수 있습니다. 이름(`silent`, `low`, `default`, `high`, `critical`) 또는 정수(`-2`..`2`)를 사용할 수 있습니다. 자세한 내용은 [메시지 우선순위 수준](https://info.pocketalert.app/api/messages/create.md#priority-levels)을 참고하세요.

적용 순서(처음 일치하는 값이 적용됨):

1. 들어오는 JSON 페이로드의 `level` 필드
2. 웹훅의 `default_level`(웹훅 생성 시 설정)
3. 애플리케이션의 기본 수준
4. `default`(일반)

직접 API와 달리 웹훅 입력은 관대하게 처리됩니다. 인식할 수 없는 `level` 값은 거부하지 않고 무시하고 기본값을 사용하므로, 알림이 누락되지 않습니다.

## 액션 버튼

웹훅은 생성하는 모든 알림에 액션 버튼을 최대 3개까지 붙일 수 있습니다. 웹훅을 만들거나 수정할 때 `actions` 필드(JSON 문자열)를 설정하세요. 자세한 내용은 [웹훅 생성 → 액션 버튼 템플릿](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template)을 참고하세요.

`label`과 `value`에는 메시지 템플릿과 같은 `%field.path%` 플레이스홀더를 사용할 수 있으므로, 들어오는 페이로드로 버튼을 구성할 수 있습니다:

```json
[
  { "type": "view", "label": "Open PR", "value": "%pull_request.html_url%" },
  { "type": "http", "label": "Merge", "value": "{\"url\":\"https://ci.example.com/merge/%pull_request.number%\",\"method\":\"POST\"}" }
]
```

치환 후 각 버튼은 검증됩니다(`type`은 `view`/`http`/`copy` 중 하나여야 하며, `view`와 `http`에는 `http(s)` URL이 필요합니다). 우선순위 수준 파싱과 마찬가지로 이 검증도 관대하게 처리됩니다. 유효하지 않은 버튼은 그 버튼만 제외되고, 나머지 버튼과 알림은 그대로 전달됩니다.

액션 버튼은 유료 기능입니다. 무료 플랜에서는 버튼이 제거된 채 알림이 전달됩니다.

웹훅을 만든 후에는 테스트해 볼 수 있습니다:

**cURL**

```bash
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
```

**JavaScript**

```javascript
await fetch('https://p4a.me/wh/YOUR_WEBHOOK_URL', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    event: { title: 'Test', message: 'Hello World' }
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://p4a.me/wh/YOUR_WEBHOOK_URL',
    json={'event': {'title': 'Test', 'message': 'Hello World'}}
)
```

**PHP**

```php
Http::post('https://p4a.me/wh/YOUR_WEBHOOK_URL', [
    'event' => [
        'title' => 'Test',
        'message' => 'Hello World',
    ],
]);
```

이렇게 하면 설정한 메시지 템플릿을 사용해 기기로 테스트 알림이 전송됩니다.
