웹훅
앱의 이벤트(발행·수정·삭제·리액션…)를 백엔드가 HTTP로 받는다. 푸시 알림, 검색 색인, 감사 로그, 외부 시스템 동기화가 여기 붙는다.
웹훅 주소는 콘솔의 웹훅 화면에서 설정한다. 앱 개요 옆 "웹훅" 탭에서 받을 주소(와 필요하면
before_publish)를 넣으면, 서명 시크릿을 그 화면이 한 번 보여 준다 — 콘솔은 이 값을 저장하지 않으니 그 자리에서 엔드포인트의 검증 코드에 옮겨 적는다.
받는 코드
import express from 'express'
import { createChatServer } from '@kispi/chat/server'
const app = express()
const seen = new Set<string>() // 실제로는 Redis나 DB처럼 프로세스 밖에 둔다
const chat = createChatServer({
secretKey: process.env.CHAT_SECRET_KEY!,
webhookSecret: process.env.CHAT_WEBHOOK_SECRET // 콘솔의 웹훅 화면이 한 번 보여준 서명 시크릿
})
app.post('/chat-hook', express.raw({ type: 'application/json' }), (req, res) => {
let payload
try {
payload = chat.webhooks.verify(req.headers, req.body.toString('utf8'))
} catch {
return res.sendStatus(400) // 서명이 맞지 않는다. 아무것도 처리하지 않는다
}
const { event, delivery, data } = payload
if (seen.has(delivery)) return res.sendStatus(200) // at-least-once다
seen.add(delivery)
res.sendStatus(200) // 10초 안에 먼저 답하고
void handle(event, data) // 처리는 비동기로
})import hmac, hashlib, json, time
# raw_body는 받은 바이트 그대로다. 파싱한 뒤 다시 직렬화하면 서명이 맞지 않는다.
# 서명이 맞으면 파싱한 바디를, 아니면 None(→ 400)을 돌려준다.
def verify(headers, raw_body, secret):
event = headers.get("X-Chat-Event", "")
delivery = headers.get("X-Chat-Delivery", "") # before_publish에는 이 헤더가 없다
timestamp, macs = None, []
for item in headers.get("X-Chat-Signature", "").split(","):
name, _, value = item.strip().partition("=")
if name == "t":
timestamp = value
elif name == "v1":
macs.append(value) # 여러 개일 수 있고 하나라도 맞으면 통과다
if timestamp is None or not macs:
return None
if abs(time.time() - int(timestamp)) > 300: # 양방향 5분. 미래 시각도 거절이다
return None
signed = f"{timestamp}\n{event}\n{delivery}\n".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
if not any(hmac.compare_digest(expected, mac) for mac in macs):
return None
return json.loads(raw_body)받는 이벤트
요청 바디(data)가 이벤트의 내용이고, 이벤트 이름은 X-Chat-Event 헤더에, 배달 id는 X-Chat-Delivery 헤더에 있다.
chat.webhooks.verify()는 이 셋을 { event, delivery, data }로 묶어 준다. id는 13자 문자열이고 시각은 unix 밀리초다.
| 이벤트 | 언제 | data |
|---|---|---|
message.created |
메시지가 저장될 때(스레드 답글 포함) | 메시지 객체(아래) |
message.updated |
본문이 수정될 때 | 메시지 객체. editedAt이 찍혀 있다 |
message.deleted |
메시지가 지워질 때(본인 삭제, 모더레이션, 유저의 메시지 거두기 포함) | {id, seq} |
reaction.added |
리액션이 눌릴 때 | {messageId, emoji, count, userId} — count는 그 이모지의 현재 개수 |
reaction.removed |
리액션이 취소될 때 | 위와 같다 |
thread.updated |
스레드 루트에 답글이 달리거나 지워질 때 | {rootId, count, lastSeq, lastAt} |
read |
멤버의 읽음 커서가 앞으로 움직일 때 | {userId, seq, threadId?} |
member.joined |
멤버가 방에 들어올 때 | {userId, role} |
member.left |
멤버가 방에서 나갈 때 | {userId} |
room.updated |
방의 key·name·meta가 바뀔 때 |
방 객체 {id, appId, key?, type, name?, meta, lastSeq, minSeq, createdAt, updatedAt} |
room.deleted |
방이 삭제될 때 | {roomId} |
{
"roomId": "0K3M9X2T5Q8RA",
"id": "0K3M9X4B7N1HC",
"appId": "0K3M8Y1P6D5WE",
"seq": 42,
"sender": { "id": "u_42", "name": "한나" },
"kind": "text",
"body": { "text": "안녕" },
"clientMsgId": "c_1",
"createdAt": 1760000000000
}메시지 객체에는 해당할 때만 replyTo, threadId, mentions(멘션된 유저의 외부 id 배열), meta, appMeta,
editedAt, deletedAt이 더 있고, body에는 attachments와 entities가 실릴 수 있다. 리액션 집계와 스레드
집계는 싣지 않는다 — 각각 reaction.*와 thread.updated로 따로 온다.
- 방 id는
message.created·message.updated의roomId,room.deleted의roomId,room.updated의id에만 있다. 나머지 이벤트의 페이로드에는 방 id가 없다. - 콘솔에는 받을 이벤트를 고르는 설정이 없어서 위 이벤트가 전부 온다. 특히
read는 멤버의 읽음 커서가 움직일 때마다 한 건씩 오는, 가장 자주 오는 이벤트다. 필요하지 않은 이벤트는X-Chat-Event(또는event)로 가려 200만 답하고 버린다. typing·presence·custom·notification.message·user.presence는 저장되지 않는 이벤트라 웹훅으로 오지 않는다.
지킬 것 넷
- 바디는 raw 그대로 검증한다. 서명은 받은 바이트에 대한 것이라, JSON으로 파싱했다가
다시 직렬화한 문자열로는 맞지 않는다. 프레임워크의 JSON 파서가 먼저 바디를 먹지 않게 이
라우트만 raw로 받는다(Express는
express.raw, SvelteKit은await request.text()). - 배달은 at-least-once다. 같은 배달이 두 번 올 수 있다. 모든 배달에는
deliveryid가 있고 재시도해도 바뀌지 않는다. 처리한 것을 기억해 두고 두 번째는 200만 답한다. - 10초 안에 2xx로 답한다. 넘기거나 2xx가 아니면 실패로 치고 백오프가 시작된다(1초 → 5초 → 25초 → 2분 → 10분). 실패하면 그 앱의 배달은 그 이벤트에서 기다리고 뒤의 것을 먼저 보내지 않는다. 1시간 넘게 이어지면 배달이 멈춘다(아래 「배달이 멈췄을 때」). 무거운 일은 큐에 넣고 먼저 답한다.
- 순서는 방 안에서만 보장된다. 한 메시지에 대한 이벤트(
message.created→reaction.added→message.deleted)는 뒤집히지 않지만, 다른 방의 이벤트끼리는 뒤집힐 수 있다.
배달이 멈췄을 때
엔드포인트가 처음 실패한 때부터 1시간 넘게 계속 실패하면 엔진이 그 앱의 배달을 멈춘다. 이 멈춤은 저절로 풀리지 않는다 — 엔드포인트가 다시 살아나도 사람이 재개하기 전에는 이벤트가 한 건도 가지 않는다. 쌓인 이벤트는 건너뛰지 않고 큐에 그대로 남는다.
- 콘솔의 앱 웹훅 화면에 "이 앱의 웹훅 전송이 멈췄습니다" 안내가 뜬다. 멈추기 전에는 "웹훅 전송이 밀려 있습니다" 경고가 먼저 보이고, 미전송 건수와 가장 오래된 이벤트의 나이도 같은 화면에 있다.
- 엔드포인트가 2xx로 답하는지 먼저 고친다.
- 안내의 다시 시작을 누르고 확인 창에서 다시 시작을 한 번 더 누른다. 멈춘 지점부터 순서대로 배달된다.
놓친 것 따라잡기
엔드포인트가 한동안 죽어 있었으면 chat.events.list({ after, limit })로 지난 이벤트를 읽어
따라잡는다. 각 항목은 { delivery, event, createdAt, data }이고 data는 웹훅이 POST하는 바디와
같다. 마지막으로 처리한 delivery를 after로 주고, 빈 cursor가 오면 그게 전부였다는 뜻이다.
여기서도 delivery로 중복을 거른다 — 같은 이벤트가 웹훅과 이 목록 양쪽에서 올 수 있다.
배달이 끝난 이벤트는 7일까지만 남으니 따라잡기를 그보다 미루지 않는다.
이 목록은 웹훅 URL이 설정된 앱에서만 쌓인다. URL이 없는 동안 일어난 일은 나중에 URL을 설정해도 목록에 없다.
before_publish — 발행 전에 끼어들기
켜 두면 발행과 편집이 엔드포인트를 동기로 지나간다. 거절하거나 본문을 바꿔 돌려줄 수 있는 유일한 웹훅이다. 금칙어 치환, 이미지 모더레이션, 스팸 차단이 여기 산다.
→ { "event": "before_publish", "op": "create" | "update", "messageId"?: "…",
"room": "…", "sender": {…}, "kind": "text", "body": {…}, "meta"?: {…} }
← { "action": "allow" | "deny", "body"?: {…}, "appMeta"?: {…},
"code"?: "…", "message"?: "…" }- 검증하는 방법은 같다. 다만 질문이라
delivery가 없고 중복 제거 대상이 아니다. deny면 보낸 사람의send가moderation_denied로 실패하고, 엔드포인트가 준code가 클라이언트의err.appCode에,message가 에러 문구에 실린다.body를 돌려주면 그것으로 바꿔 저장하고 방송한다. 바뀐 본문도 크기 검사를 다시 받는다.action이allow/deny가 아니면 실패로 친다. 오타가 모더레이션 우회가 되지 않게.- 엔드포인트가 타임아웃되거나 에러면 기본은 **
allow**다.deny로 바꿀 수도 있지만, 그러면 엔드포인트가 죽었을 때 그 앱의 발행이 전부 멈춘다. - 서버 API(
sk_)로 보내는 메시지는 심사하지 않는다.
빨라야 한다. 이 호출이 끝날 때까지 보낸 사람의 메시지가 기다리고, 제한 시간은 1.5초다.
로컬에서 받기
웹훅 주소는 https여야 하고 엔진이 인터넷으로 닿을 수 있어야 한다. localhost·사설 IP는 받지 않는다.
로컬 개발 서버로 받으려면 cloudflared(cloudflared tunnel --url http://localhost:3000)나 ngrok 같은 터널을 띄우고,
터널이 준 https 주소를 웹훅 화면이나 콘솔 API의 PATCH /api/apps/{id}/webhook에 넣는다.
터널 주소는 다시 띄울 때마다 바뀔 수 있으니 그때마다 고친다.
터널은 왕복마다 수백 ms를 더한다. before_publish를 켰다면 제한 시간 1.5초를 넘기기 쉽고, 넘기면 기본값대로 **allow**로
지나간다 — 로컬에서 심사가 안 먹는 것처럼 보이면 터널 지연부터 의심한다. 시험하는 동안 beforePublishOnError를 deny로 두면 시간 초과가 moderation_denied로 드러난다.
다른 언어로 검증하기
요청에 헤더 셋이 온다.
| 헤더 | |
|---|---|
X-Chat-Event |
이벤트 이름. before_publish면 그 값이 온다 |
X-Chat-Delivery |
배달 id. before_publish에는 이 헤더가 없다 |
X-Chat-Signature |
t=<unix 초>,v1=<hex>. 엔진은 지금 v1을 하나 보낸다. 검증 코드는 v1이 여러 개 와도 읽고 하나라도 맞으면 통과시키도록 짠다 |
서명 입력은 네 조각을 줄바꿈(\n)으로 이은 것이다.
<t>
<X-Chat-Event>
<X-Chat-Delivery, 없으면 빈 문자열>
<받은 바디 바이트 그대로>v1은 hex(HMAC-SHA256(웹훅 시크릿, 서명 입력))이다. 시크릿은 sk_가 아니라 콘솔의 웹훅
화면이 따로 보여준 웹훅 시크릿이다. 지금 - t의 절대값이 5분을 넘으면 거절한다(양방향 —
미래 시각도 거절이다). 재시도는 t만 갱신하고 X-Chat-Delivery는 유지하므로, 중복 제거는 그 값으로 한다.
시크릿 교체
콘솔의 앱 웹훅 화면에서 시크릿 교체를 누르고 확인하면 새 웹훅 시크릿이 그 자리에서 한 번 보인다.
옛 시크릿과 새 시크릿이 겹치는 기간은 없다. 서명은 늘 시크릿 하나(v1 하나)로 하므로, 교체한 순간부터
모든 배달이 새 시크릿으로 서명된다. 밀려 있던 이벤트와 재시도 중인 이벤트도 마찬가지고, 옛 시크릿으로는 더
이상 검증되지 않는다.
- 시크릿 교체를 누르고 새 시크릿을 복사한다.
- 엔드포인트의 웹훅 시크릿(예:
CHAT_WEBHOOK_SECRET)을 새 값으로 바꿔 바로 배포한다. - 배포가 끝나기 전에 온 배달은 서명이 맞지 않아 실패로 기록되고 백오프로 다시 온다. 1시간 안에 배포하면 빠지는 이벤트가 없다. 그보다 길어져 배달이 멈췄다면 웹훅 화면에서 다시 시작을 누른다.