웹훅 완전 정복: 실시간 이벤트를 안전하게 수신하는 방법
KiroAPI 웹훅을 사용하면 이벤트 발생 시 지정된 URL로 즉시 데이터를 푸시받을 수 있습니다. 이 가이드에서는 설치부터 프로덕션 배포까지 단계별로 살펴봅니다.
박서연
개발자 경험팀 · KiroAPI
소개
전통적인 폴링 방식은 서버에 불필요한 요청을 반복적으로 보냅니다. KiroAPI 웹훅은 이 문제를 근본적으로 해결합니다. 결제 완료, 사용자 가입, 파일 업로드 등 모든 이벤트를 실시간으로 수신하고 처리할 수 있습니다.
참고
웹훅은 KiroAPI Pro 이상 플랜에서 사용할 수 있습니다. Starter 플랜에서는 최대 5개 동시 연결까지 지원됩니다.
설치 및 초기화
SDK를 설치하고 클라이언트를 초기화합니다. TypeScript를 기준으로 설명합니다.
$ npm install @kiro/sdk
import { KiroAPI, WebhookEvent } from '@kiro/sdk';
const client = new KiroAPI({
apiKey: process.env.KIRO_API_KEY,
region: 'ap-northeast-2',
});
웹훅 수신 설정
웹훅 엔드포인트를 Express.js로 구성하는 예제입니다. 서명 검증은 필수입니다.
주의
서명 검증 없이 웹훅을 수신하면 보안 취약점이 발생합니다. 반드시 kiro-signature 헤더를 검증하세요.
app.post('/webhook', async (req, res) => {
// 서명 검증
const sig = req.headers['kiro-signature'];
const event = await client.webhooks.verify(req.body, sig);
switch (event.type) {
case 'payment.completed':
awaithandlePayment(event.data);
break;
}
res.json({ received: true });
});
팁
로컬 개발 시 kiro listen --forward http://localhost:3000/webhook 명령으로 CLI 터널을 사용할 수 있습니다.