Webhook

일반 webhook 채널은 폴백 입니다. Ongrid 가 네이티브로 말하지 않는 채팅 표면, 티켓 시스템, 사내 relay (Microsoft Teams, Mattermost, Rocket Chat, OpsGenie, PagerDuty, 자체 라우터) 로 알림을 push 해야 할 때, 일반 webhook 을 그곳으로 가리키면 알림 파이프라인이 정규 Ongrid 메시지 JSON 을 게시합니다.

전용 채널이 있다면 사용

Slack / Feishu / DingTalk / WeCom / Telegram 은 전용 채널이 더 풍부한 payload (Slack attachments, 서명) 를 렌더링합니다. 전용 채널이 없을 때만 일반 webhook 에 손을 뻗으세요.

Payload

body 는 정규 notify.Message 형태이며 JSON 인코딩된 그대로:

json

{
  "severity": "critical",
  "subject": "node-01 swap_high",
  "body": "swap_in_pages > 1000 for 5m",
  "source": "alert",
  "labels": {
    "rule": "swap_high",
    "incident_id": "1234",
    "device_id": "7",
    "host": "node-01"
  },
  "dedupe_key": "alert:swap_high:device=7",
  "occurred_at": "2026-05-30T14:02:35Z"
}

envelope 없음, msgtype 없음, 평탄화 없음. 수신자는 알림 파이프라인이 생성한 필드를 정확히 받습니다. NewGenericWebhookSender 가 빌드.

선택적 HMAC 서명

Secret 필드를 채우면 모든 요청에 X-Ongrid-Signature 헤더가 실립니다.

text

X-Ongrid-Signature: sha256=<hex>

<hex> 는 게시된 정확한 바이트 위의 hex(HMAC-SHA256(secret, body)). signer 는 signGenericWebhook.

수신자 측 검증

python

# Python receiver
import hmac, hashlib

def verify(secret, body_bytes, header):
    expected = "sha256=" + hmac.new(
        secret.encode(), body_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

// Go receiver
func verify(secret string, body, header []byte) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := []byte("sha256=" + hex.EncodeToString(mac.Sum(nil)))
    return hmac.Equal(expected, header)
}

엔드포인트가 공개라면 항상 서명을 검증하세요

서명 없는 일반 webhook URL 은 URL 을 아는 누구에게나 열려 있습니다. 서명 헤더는 "이는 Ongrid 로부터 왔다" 를 인증하는 유일한 것입니다.

요청 형태

Property	Value
Method	`POST`
`Content-Type`	`application/json`
`User-Agent`	`ongrid-notify/1.0`
Body	`notify.Message` 의 JSON
Sig 헤더	`X-Ongrid-Signature: sha256=…` (시크릿이 있을 때만)
Timeout	요청별 `http.Client` 타임아웃 (기본 15s)

성공 기준

Sender 는 HTTP 2xx (200–299) 를 성공으로 취급. 그 외 모든 것 — 3xx 리다이렉트, 4xx, 5xx — 은 unexpected status: … 이며 댐핑 파이프라인에 실패한 전달로 카운트. 응답 body 는 파싱되지 않음. Ongrid 는 relay 가 무슨 JSON 을 메아리쳐도 신경 쓰지 않습니다.

재시도와 댐핑

재시도 의미는 Sender 가 아닌 알림 파이프라인 이 소유. Sender 는 Send(ctx, msg) 호출당 정확히 한 번 게시. 파이프라인이 결정:

댐핑 윈도우. 규칙별, 기본 5 분. 같은 dedupe 키는 윈도우당 최대 한 번 발화.
계속 발화 시 반복. 기본 1 시간. incident 가 이 윈도우 후에도 열려 있으면 채팅 기록에서 잃지 않도록 채널이 재알림을 받음.
회복 메시지. 알림이 해제되면 발화.

Sender 의 일은 바이트를 push 하는 것. 파이프라인의 일은 언제 할지 결정하는 것.

전송 실패 시 자동 재시도 없음

Sender 가 게시할 때 수신자가 다운되어 있으면 메시지는 손실 됩니다 (전달 에러로 로깅되어 채널별 전달 통계에 표면화). 파이프라인은 큐잉하지 않으며 나중에 재시도하지 않습니다. 이유: 회복 3 분 후 전달되는 5 분 지연 알림은 사라진 것보다 더 혼란스럽습니다. 견고한 수신자를 사용하거나 Ongrid 와 불안정한 다운스트림 사이에 자체 큐를 레이어로 두세요.

설정

POST + application/json 을 수락하는 HTTP 엔드포인트 구축. Ongrid 와 공유할 강력한 시크릿 선택.
Ongrid 에서: Settings → Channels → New → Provider = webhook → Endpoint = URL → Secret = 공유 시크릿.
Test 클릭. 테스트 메시지는 합성된 notify.Message{Severity: "info", Subject: "Ongrid test", …}. 수신자 로그에서 서명 헤더 검증.

레시피

Microsoft Teams (incoming webhook)

Teams 의 incoming webhook 은 다른 payload 형태 (MessageCard) 를 수락. 가장 간단한 경로는 Ongrid 와 Teams 사이에 작은 어댑터를 두는 것:

python

# server.py - listens on /ongrid-to-teams
@app.post("/ongrid-to-teams")
def relay(msg: dict):
    teams_url = os.environ["TEAMS_WEBHOOK"]
    card = {
        "@type": "MessageCard",
        "@context": "https://schema.org/extensions",
        "themeColor": {"critical":"D92F2F","warning":"F2C037","info":"36A64F"}.get(msg["severity"], "6F7A87"),
        "title": msg["subject"],
        "text": msg["body"],
    }
    requests.post(teams_url, json=card)

Ongrid webhook 채널을 https://your-relay/ongrid-to-teams 로 가리키세요.

PagerDuty Events API v2

같은 패턴: {severity, subject, body, dedupe_key} 를 PagerDuty events.v2 payload 로 번역하는 작은 relay. PD dedup_key 필드가 Ongrid 의 dedupe_key 와 1:1 매핑되므로 Ongrid 의 같은 incident 는 PD 의 같은 알림.

Splunk HEC / Elastic ingest

URL 에 Splunk 토큰을 담아 HEC 엔드포인트로 채널을 가리키세요. Splunk 는 정규 Ongrid JSON 을 수락; 다운스트림 검색용으로 severity 와 labels.rule 에 인덱스.

필드 레퍼런스

진실의 원천은 Message 참고. 안정 필드:

Field	Type	Notes
`severity`	string	`critical` / `warning` / `info`.
`subject`	string	규칙 이름 + 대상 — 한 줄.
`body`	string	멀티라인 상세. 개행 포함 가능.
`source`	string	`alert` / `test` 등.
`labels`	map[string]string	`rule`, `incident_id`, `device_id`, 커스텀.
`dedupe_key`	string	`pipeline:rule:label-set`. identity 별 안정.
`occurred_at`	RFC3339 string	UTC. 알림 evaluator 가 발화한 순간.

새 필드는 가산 — 수신자는 알 수 없는 키를 무시해야 합니다.

Webhook ​

Payload ​

선택적 HMAC 서명 ​

수신자 측 검증 ​

요청 형태 ​

성공 기준 ​

재시도와 댐핑 ​

설정 ​

레시피 ​

Microsoft Teams (incoming webhook) ​

PagerDuty Events API v2 ​

Splunk HEC / Elastic ingest ​

필드 레퍼런스 ​

관련 ​