Webhooks

Webhook을 사용하면 AskAIs Customer Service 이벤트를 자체 시스템에 미러링할 수 있습니다 — CRM, 분석 도구, Slack 등 HTTP로 통신하는 모든 시스템에.

Webhook 만들기

설정 → Webhooks → 새 Webhook으로 이동하세요. 이벤트를 선택하고 URL을 붙여넣은 후 저장합니다. 페이로드 서명에 사용되는 시크릿을 받게 됩니다.

이벤트 유형

• conversation.created
• conversation.updated — 상태, 우선순위, 할당
• conversation.resolved
• message.created — 모든 메시지, 모든 발신자
• contact.created
• contact.updated

페이로드 형식

POST https://your-app.com/webhooks/singlink
Content-Type: application/json
X-SingLink-Event: message.created
X-SingLink-Signature: sha256=ab12cd34...
X-SingLink-Timestamp: 1747300800

{
  "id": "evt_01HX...",
  "type": "message.created",
  "tenantId": "tnt_01HX...",
  "data": { /* event-specific payload */ }
}

서명 검증

Webhook 시크릿으로 timestamp + "." + rawBody에 대해 HMAC-SHA256을 계산합니다. 이를 X-SingLink-Signature 헤더와 비교합니다(타이밍 안전).

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req, secret) {
  const ts = req.headers["x-singlink-timestamp"];
  const sig = req.headers["x-singlink-signature"];
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

재시도

2xx가 아닌 응답은 지수 백오프로 재시도합니다: 1s, 10s, 1m, 10m, 1h. 5회 시도 후 이벤트는 실패로 표시되며, 관리자에서 실패 내역을 확인할 수 있습니다.

테스트 ping

각 Webhook에는 더미 webhook.ping 이벤트를 전송하는 테스트 전송 버튼이 있습니다. 운영에 들어가기 전에 엔드포인트가 서명을 수락하는지 확인하는 데 유용합니다.