웹훅

앱의 이벤트(발행·수정·삭제·리액션…)를 백엔드가 HTTP로 받는다. 푸시 알림, 검색 색인, 감사 로그, 외부 시스템 동기화가 여기 붙는다.

웹훅 주소는 콘솔의 웹훅 화면에서 설정한다. 앱 개요 옆 "웹훅" 탭에서 받을 주소(와 필요하면 before_publish)를 넣으면, 서명 시크릿을 그 화면이 한 번 보여 준다 — 콘솔은 이 값을 저장하지 않으니 그 자리에서 엔드포인트의 검증 코드에 옮겨 적는다.

받는 코드

ts
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) // 처리는 비동기로
})
python
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}
json
{
  "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는 저장되지 않는 이벤트라 웹훅으로 오지 않는다.

지킬 것 넷

  1. 바디는 raw 그대로 검증한다. 서명은 받은 바이트에 대한 것이라, JSON으로 파싱했다가 다시 직렬화한 문자열로는 맞지 않는다. 프레임워크의 JSON 파서가 먼저 바디를 먹지 않게 이 라우트만 raw로 받는다(Express는 express.raw, SvelteKit은 await request.text()).
  2. 배달은 at-least-once다. 같은 배달이 두 번 올 수 있다. 모든 배달에는 delivery id가 있고 재시도해도 바뀌지 않는다. 처리한 것을 기억해 두고 두 번째는 200만 답한다.
  3. 10초 안에 2xx로 답한다. 넘기거나 2xx가 아니면 실패로 치고 백오프가 시작된다(1초 → 5초 → 25초 → 2분 → 10분). 실패하면 그 앱의 배달은 그 이벤트에서 기다리고 뒤의 것을 먼저 보내지 않는다. 1시간 넘게 이어지면 배달이 멈춘다(아래 「배달이 멈췄을 때」). 무거운 일은 큐에 넣고 먼저 답한다.
  4. 순서는 방 안에서만 보장된다. 한 메시지에 대한 이벤트(message.created → reaction.added → message.deleted)는 뒤집히지 않지만, 다른 방의 이벤트끼리는 뒤집힐 수 있다.

배달이 멈췄을 때

엔드포인트가 처음 실패한 때부터 1시간 넘게 계속 실패하면 엔진이 그 앱의 배달을 멈춘다. 이 멈춤은 저절로 풀리지 않는다 — 엔드포인트가 다시 살아나도 사람이 재개하기 전에는 이벤트가 한 건도 가지 않는다. 쌓인 이벤트는 건너뛰지 않고 큐에 그대로 남는다.

  1. 콘솔의 앱 웹훅 화면에 "이 앱의 웹훅 전송이 멈췄습니다" 안내가 뜬다. 멈추기 전에는 "웹훅 전송이 밀려 있습니다" 경고가 먼저 보이고, 미전송 건수와 가장 오래된 이벤트의 나이도 같은 화면에 있다.
  2. 엔드포인트가 2xx로 답하는지 먼저 고친다.
  3. 안내의 다시 시작을 누르고 확인 창에서 다시 시작을 한 번 더 누른다. 멈춘 지점부터 순서대로 배달된다.

놓친 것 따라잡기

엔드포인트가 한동안 죽어 있었으면 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 하나)로 하므로, 교체한 순간부터 모든 배달이 새 시크릿으로 서명된다. 밀려 있던 이벤트와 재시도 중인 이벤트도 마찬가지고, 옛 시크릿으로는 더 이상 검증되지 않는다.

  1. 시크릿 교체를 누르고 새 시크릿을 복사한다.
  2. 엔드포인트의 웹훅 시크릿(예: CHAT_WEBHOOK_SECRET)을 새 값으로 바꿔 바로 배포한다.
  3. 배포가 끝나기 전에 온 배달은 서명이 맞지 않아 실패로 기록되고 백오프로 다시 온다. 1시간 안에 배포하면 빠지는 이벤트가 없다. 그보다 길어져 배달이 멈췄다면 웹훅 화면에서 다시 시작을 누른다.