웹훅 설정
들어오는 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 페이로드
다음과 같은 웹훅 페이로드가 들어온다고 가정해 보겠습니다:
{
"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"]}
]
}
}템플릿 설정
*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 웹훅
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%Sentry 오류 추적
알림 액션(이슈 알림)으로 사용하는 내부 연동의 경우:
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%이슈를 열 view 버튼을 %data.event.web_url%과 함께 추가하세요. 레거시 Webhooks 플러그인은 다른 페이로드를 보냅니다. 이 경우에는 %project_name%: %event.title%과 %url%을 사용하세요.
Grafana 알림
⚠️ %state%: %title%
%message%
Status: %status%Uptime Robot
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%고급 경로 문법
복잡한 JSON 추출에는 GJSON Path Syntax를 사용합니다.
유용한 패턴
| 패턴 | 설명 |
|---|---|
%users.#% | 배열 항목 수 |
%users.#.first% | 모든 first 값의 배열 |
%users.@reverse% | 배열 순서 뒤집기 |
%data.@pretty% | JSON 보기 좋게 출력 |
더 알아보기
전체 문서: GJSON Path Syntax
우선순위 수준
들어오는 페이로드에 level 필드를 포함해 푸시 알림의 전달 방식을 제어할 수 있습니다. 이름(silent, low, default, high, critical) 또는 정수(-2..2)를 사용할 수 있습니다. 자세한 내용은 메시지 우선순위 수준을 참고하세요.
적용 순서(처음 일치하는 값이 적용됨):
- 들어오는 JSON 페이로드의
level필드 - 웹훅의
default_level(웹훅 생성 시 설정) - 애플리케이션의 기본 수준
default(일반)
직접 API와 달리 웹훅 입력은 관대하게 처리됩니다. 인식할 수 없는 level 값은 거부하지 않고 무시하고 기본값을 사용하므로, 알림이 누락되지 않습니다.
액션 버튼
웹훅은 생성하는 모든 알림에 액션 버튼을 최대 3개까지 붙일 수 있습니다. 웹훅을 만들거나 수정할 때 actions 필드(JSON 문자열)를 설정하세요. 자세한 내용은 웹훅 생성 → 액션 버튼 템플릿을 참고하세요.
label과 value에는 메시지 템플릿과 같은 %field.path% 플레이스홀더를 사용할 수 있으므로, 들어오는 페이로드로 버튼을 구성할 수 있습니다:
[
{ "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 -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"event": {"title": "Test", "message": "Hello World"}}'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' }
})
});import requests
requests.post(
'https://p4a.me/wh/YOUR_WEBHOOK_URL',
json={'event': {'title': 'Test', 'message': 'Hello World'}}
)Http::post('https://p4a.me/wh/YOUR_WEBHOOK_URL', [
'event' => [
'title' => 'Test',
'message' => 'Hello World',
],
]);이렇게 하면 설정한 메시지 템플릿을 사용해 기기로 테스트 알림이 전송됩니다.