리소스Resources · v1 preview

웹훅Webhooks

이벤트를 당신의 HTTPS 엔드포인트로 서명된 POST 로 보내요. Pro 이상에서 엔드포인트를 등록할 수 있어요.

POST /v1/public/webhooks
{ "url": "https://example.com/vdas/hook", "events": ["shot.completed", "alert.raised"], "machines": ["VDAS-PRO1G-2644-9999"] }
→ 201 { "id": "wh_01JB…", "secret": "whsec_…" }   # secret 은 1회만

이벤트 목록

이벤트	언제	페이로드 요점
`shot.completed`	샷 레코드가 업로드·확정될 때	샷 요약 (`fields=summary` 와 같음) + `shot_url`
`shot.updated`	별점·메모가 바뀔 때	`id`, 바뀐 필드
`machine.checkin`	연결 상태가 바뀔 때 (`connected` true↔false)	장치 키, 마지막 체크인
`ota.applied`	번들 적용 잡이 끝날 때	잡 ID, 결과(`succeeded`·`failed`·`cancelled`), 단계별 결과
`alert.raised` · `alert.cleared`	과열 래치·센서 센티넬·체크인 유실	코드, 채널, 값
`settings.changed`	허용 목록 설정이 어디서든 바뀔 때	키, 새 값, 출처(`api`·`screen`·`web`)

서명 검증

POST /vdas/hook
X-VDAS-Event: shot.completed
X-VDAS-Delivery: dl_01JB…
X-VDAS-Timestamp: 1761739441
X-VDAS-Signature: v1=hex(HMAC-SHA256(secret, timestamp + "." + body))

# 5분 넘은 timestamp 는 거부. 같은 X-VDAS-Delivery 는 멱등 처리.

재시도

2xx 가 아니면 1 분 · 5 분 · 30 분 · 2 시간 · 12 시간 간격으로 5회 재시도해요. 24시간 연속 실패하면 엔드포인트를 paused 로 두고 GET /v1/public/webhooks/{id}/deliveries 에서 사유를 볼 수 있어요.

Events are delivered as signed HTTPS POSTs. Pro and above can register endpoints.

POST /v1/public/webhooks
{ "url": "https://example.com/vdas/hook", "events": ["shot.completed","alert.raised"] }

Event	When
`shot.completed`	a shot record is uploaded and finalised
`shot.updated`	rating or notes change
`machine.checkin`	connected flips
`ota.applied`	a bundle job finishes
`alert.raised` / `alert.cleared`	overtemp latch, sensor sentinel, check-in lost
`settings.changed`	an allow-listed setting changes anywhere

X-VDAS-Signature: v1=hex(HMAC-SHA256(secret, timestamp + "." + body))
# reject timestamps older than 5 min; treat X-VDAS-Delivery as idempotency key

Retries: 1 min, 5 min, 30 min, 2 h, 12 h; paused after 24 h of failures.