웹훅은 곧 출시 예정입니다. 이 페이지는 계획된 기능을 설명합니다.
계획된 이벤트
| 이벤트 | 설명 | 사용 사례 |
|---|
fortune.generated | 새 운세 생성됨 | 사용자 대시보드 업데이트 |
daily.reset | 자정에 일일 운세 초기화 | 사용자에게 새 운세 알림 |
cache.warmed | 캐시 워밍 완료 | 시스템 상태 확인 |
rate_limit.warning | 요청 제한 도달 임박 | 운영팀 알림 |
웹훅 페이로드 형식
{
"id": "evt_abc123",
"type": "fortune.generated",
"created": "2025-01-15T09:00:00Z",
"data": {
"dayMaster": "병화",
"date": "2025-01-15",
"score": 78,
"model": "haiku"
}
}
웹훅 보안
모든 웹훅에는 검증용 서명 헤더가 포함됩니다:
import crypto from 'crypto';
function verifyWebhook(
payload: string,
signature: string,
secret: string
): boolean {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// Express 미들웨어
app.post('/webhooks/saju', (req, res) => {
const signature = req.headers['x-saju-signature'];
const isValid = verifyWebhook(
JSON.stringify(req.body),
signature,
process.env.WEBHOOK_SECRET
);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
// 웹훅 처리
handleWebhook(req.body);
res.status(200).send('OK');
});
재시도 정책
실패한 웹훅 전송은 지수 백오프로 재시도됩니다:
5번 실패 후 웹훅은 실패로 표시되며 이메일 알림을 받게 됩니다.
웹훅 관리
웹훅 등록 (예정)
curl -X POST https://api.sajuapi.dev/webhooks \
-H "X-API-Key: bs_live_xxx" \
-d '{
"url": "https://your-app.com/webhooks/saju",
"events": ["fortune.generated", "daily.reset"]
}'
웹훅 목록 조회 (예정)
curl https://api.sajuapi.dev/webhooks \
-H "X-API-Key: bs_live_xxx"
웹훅 삭제 (예정)
curl -X DELETE https://api.sajuapi.dev/webhooks/wh_abc123 \
-H "X-API-Key: bs_live_xxx"
대안: 폴링
웹훅이 출시되기 전까지 폴링으로 업데이트를 확인할 수 있습니다:
// 매시간 새 운세 데이터 폴링
setInterval(async () => {
const response = await fetch('/api/daily-fortune', {
method: 'POST',
headers: { 'X-API-Key': API_KEY },
body: JSON.stringify({ saju, userName, date: today })
});
const { data, meta } = await response.json();
if (!meta.cached) {
// 새 운세 생성됨
notifyUser(data);
}
}, 60 * 60 * 1000);
알림 받기
웹훅 출시 알림을 받고 싶으신가요?
대기 목록 등록
웹훅 베타 대기 목록에 등록하려면 이메일을 보내주세요.
