웹훅
Connect Base 웹훅 심화 가이드입니다.
개요
웹훅을 사용하면 Connect Base에서 발생하는 이벤트를 실시간으로 외부 시스템에 전달할 수 있습니다.
지원 이벤트
데이터베이스 이벤트
| 이벤트 | 설명 |
|---|---|
table.data.created | 데이터 생성 |
table.data.updated | 데이터 수정 |
table.data.deleted | 데이터 삭제 |
스토리지 이벤트
| 이벤트 | 설명 |
|---|---|
storage.file.uploaded | 파일 업로드 |
storage.file.deleted | 파일 삭제 |
사용자 이벤트
| 이벤트 | 설명 |
|---|---|
user.created | 사용자 가입 |
user.updated | 사용자 정보 수정 |
user.deleted | 사용자 삭제 |
서명 검증
모든 웹훅 요청에는 X-ConnectBase-Signature 헤더가 포함됩니다.
Node.js 검증
javascript
import crypto from 'crypto'
function verifySignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex')
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
)
}
// Express 예시
app.post('/webhooks', (req, res) => {
const signature = req.headers['x-connectbase-signature']
if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature')
}
// 이벤트 처리
console.log('Event:', req.body.type)
res.status(200).send('OK')
})Python 검증
python
import hmac
import hashlib
def verify_signature(payload, signature, secret):
expected = hmac.new(
secret.encode(),
json.dumps(payload).encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)재시도 정책
웹훅 전송 실패 시 자동으로 재시도합니다:
| 시도 | 대기 시간 |
|---|---|
| 1차 | 즉시 |
| 2차 | 1분 |
| 3차 | 5분 |
| 4차 | 30분 |
| 5차 | 1시간 |
모범 사례
1. 빠르게 응답
웹훅 핸들러는 5초 내에 200 응답을 반환해야 합니다:
javascript
// ✅ 빠른 응답
app.post('/webhooks', async (req, res) => {
// 즉시 200 응답
res.status(200).send('OK')
// 백그라운드에서 처리
processEventAsync(req.body)
})2. 멱등성 보장
같은 이벤트가 여러 번 전달될 수 있으므로 멱등성을 보장하세요:
javascript
app.post('/webhooks', async (req, res) => {
const eventId = req.body.id
// 이미 처리된 이벤트인지 확인
if (await isProcessed(eventId)) {
return res.status(200).send('Already processed')
}
await processEvent(req.body)
await markAsProcessed(eventId)
res.status(200).send('OK')
})3. 로깅
디버깅을 위해 모든 이벤트를 로깅:
javascript
app.post('/webhooks', (req, res) => {
console.log({
eventId: req.body.id,
type: req.body.type,
timestamp: req.body.timestamp
})
// 처리 로직...
})