Webhooks

웹훅은 dAio를 고객사 고유의 시스템과 연결합니다. 플랫폼을 지속적으로 폴링하는 대신, dAio가 먼저 알리도록 하는 방식입니다. 이벤트가 발생하는 즉시 — 기상 경보 발령, 높은 위험 감지 등 — dAio는 고객사가 지정한 엔드포인트로 서명된 HTTP 요청을 실시간으로 전송합니다. 이를 통해 티켓 발행, 내부 알림, 업무 대시보드 갱신, 현장 대응 계획 발동 등 워크플로를 자동화할 수 있습니다.

이는 dAio의 경보와 고객사 정보 시스템을 잇는 가교입니다.

구성된 웹훅 목록

팁: 먼저 단일 이벤트 유형을 구독하는 하나의 웹훅으로 시작해 엔드투엔드 연계를 검증한 뒤 확장하세요. 처리를 안정화하기 전에 시스템이 알림에 파묻히는 상황을 피할 수 있습니다.

웹훅 구성하기

설정 > 웹훅 으로 이동합니다.
새 웹훅 을 클릭합니다.
대상 URL 을 입력합니다: 고객사 서버의 HTTPS 엔드포인트입니다(예: https://votre-serveur.com/webhook).
해당 라벨을 클릭하여 수신할 이벤트 를 선택합니다.
생성 으로 확정합니다.

생성 시 시크릿이 자동으로 발급됩니다. 이는 각 요청을 HMAC-SHA256으로 서명하는 데 사용됩니다(아래 참조). 서버 측에 보관하면 각 호출이 실제로 dAio에서 발신되었는지 검증할 수 있습니다.

경고: URL은 HTTPS 여야 하며 공개적으로 접근 가능해야 합니다. 단순 HTTP 엔드포인트나 닫힌 방화벽 뒤에 있는 엔드포인트는 전송을 받을 수 없습니다.

사용 가능한 이벤트

이벤트	설명
`weather.alert`	사이트에서 기상 경보가 발령됨
`weather.threshold`	사용자 지정 기상 임계값을 초과함
`air_quality.alert`	대기질 경보가 발령됨
`pollen.alert`	꽃가루 경보가 발령됨
`marine.alert`	해상 상황 경보가 발령됨
`frost.alert`	서리 경보가 발령됨
`storm.alert`	뇌우 / 폭풍 경보가 발령됨
`business.risk_high`	고객사 비즈니스에 대해 높은 위험 수준이 감지됨

팁: 각 웹훅은 수신 시스템이 실제로 활용하는 이벤트만 구독하세요. '티켓' 엔드포인트가 '대시보드' 엔드포인트와 동일한 이벤트를 받을 필요는 없습니다.

페이로드 형식

각 전송은 본문이 JSON 객체인 POST 요청입니다. 일반적인 구조는 다음과 같습니다.

json

{
  "event": "weather.alert",
  "timestamp": "2026-06-30T08:15:00Z",
  "data": {
    "site_id": 42,
    "site_name": "Entrepôt Nord",
    "severity": "high",
    "message": "Vent fort attendu (rafales > 80 km/h)"
  }
}

event 필드는 이벤트 유형을 식별하고, timestamp 는 발신 일시(UTC, ISO 8601 형식)를 나타내며, data 는 해당 이벤트 고유의 세부 정보를 담습니다.

HMAC-SHA256 인증

각 요청은 고객사의 시크릿을 사용해 HMAC-SHA256 으로 서명됩니다. 서명은 X-Daio-Signature 헤더에 sha256=<signature> 형식으로 전달됩니다.

요청을 처리하기 전에 항상 이 서명을 검증하세요. 이는 호출이 dAio에서 발신되었고 페이로드가 변조되지 않았음을 보장합니다.

서버 측 검증(Python):

python

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

경고: 서명은 요청의 원본 본문(수신한 바이트)에 대해, JSON 역직렬화 이전에 계산하세요. 아주 미세한 재포맷만으로도 해시가 바뀌어 검증이 실패합니다.

테스트 및 디버깅

웹훅 옆의 테스트 아이콘(▶)을 클릭하면 더미 이벤트를 엔드포인트로 전송할 수 있습니다.
HTTP 2xx 응답은 서버가 요청을 올바르게 수신하고 수락했음을 확인해 줍니다.
웹훅을 펼치면 최근 전송 내역(HTTP 코드, 이벤트 유형, 타임스탬프)을 확인할 수 있습니다.
색상 점이 웹훅 상태를 나타냅니다: 녹색 = 활성, 빨간색 = 반복된 실패로 비활성화됨.

전송 이력

모든 전송은 기록됩니다. 웹훅을 펼치면 각 시도에 대해 다음을 확인할 수 있습니다.

응답 HTTP 코드(300 미만이면 녹색, 그렇지 않으면 빨간색)
전송된 이벤트 유형
시도 날짜 및 시간

전송이 실패하면 웹훅에 실패 카운터가 표시됩니다.

재시도 및 신뢰성

dAio는 실패 시 간격을 점차 늘려가며 전송을 자동으로 재시도합니다. 따라서 고객사 엔드포인트는 멱등 해야 합니다. 동일한 전송이 여러 번 도착할 수 있으며, 처리는 부작용 없이 동일한 결과를 만들어야 합니다.

경고: 고객사 엔드포인트는 10초 이내에 HTTP 2xx 코드로 응답해야 합니다. 이를 초과하거나 오류 코드를 반환하면 전송은 실패로 간주되어 재시도됩니다. 반복적으로 실패하면 웹훅은 자동으로 비활성화됩니다.

모범 사례

항상 서명을 검증하세요: 페이로드를 처리하기 전에 반드시 HMAC 서명을 검증하고, 인증되지 않은 요청은 결코 신뢰하지 마세요.
빠르게 응답하세요: 즉시 200 을 반환한 뒤 작업은 백그라운드에서 처리하세요. 타임아웃과 불필요한 재시도를 방지할 수 있습니다.
처리를 멱등하게 만드세요: 중복 전송을 위험 없이 흡수할 수 있습니다.
소스에서 필터링하세요: 각 웹훅은 해당 수신 시스템에 유용한 이벤트만 구독하도록 하세요.
실패 카운터를 모니터링하세요: 전송 이력과 함께 확인하여, 비활성화되기 전에 고장 난 엔드포인트를 신속히 감지하세요.
테스트 버튼을 활용하세요: 고객사 측에서 변경(배포, URL 변경)이 있을 때마다 실제 이벤트를 기다리지 않고 연계를 검증하세요.

팁: 웹훅을 경보 및 팀 설정과 결합하면 적절한 정보를 적절한 시스템으로 자동 전달할 수 있습니다. 웹훅의 이용 가능 여부는 고객사의 구독에 따라 달라집니다.

Webhooks ​

웹훅 구성하기 ​

사용 가능한 이벤트 ​

페이로드 형식 ​

HMAC-SHA256 인증 ​

테스트 및 디버깅 ​

전송 이력 ​

재시도 및 신뢰성 ​

모범 사례 ​