배송 상태가 변경될 때마다 API를 폴링하는 대신, 웹훅을 사용하면 자동으로 알림을 받을 수 있습니다.

🎯 웹훅의 장점
• 실시간 알림 수신 (폴링 불필요)
• API 호출 횟수 절감 (비용 절감)
• 서버 부하 감소
• 배송 상태 변경 즉시 대응

웹훅 작동 원리

배송 상태가 변경되면 DeliveryAPI 서버가 여러분의 서버로 HTTP POST 요청을 보냅니다.

배송 접수 → DeliveryAPI 감지 → 웹훅 POST → 여러분의 서버

1단계: 웹훅 엔드포인트 생성

Express.js 예제

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/delivery', (req, res) => {
  const event = req.body;
  
  console.log('웹훅 이벤트:', event);
  
  // 이벤트 타입별 처리
  switch(event.type) {
    case 'delivery.picked_up':
      console.log('집화 완료:', event.data.trackingNumber);
      // 고객에게 집화 알림 발송
      break;
      
    case 'delivery.in_transit':
      console.log('배송중:', event.data.trackingNumber);
      break;
      
    case 'delivery.out_for_delivery':
      console.log('배송 출발:', event.data.trackingNumber);
      // 고객에게 배송 출발 알림
      break;
      
    case 'delivery.delivered':
      console.log('배송 완료:', event.data.trackingNumber);
      // 배송 완료 처리
      break;
      
    case 'delivery.failed':
      console.log('배송 실패:', event.data.trackingNumber);
      // 관리자 알림
      break;
  }
  
  // 200 응답 필수! (3초 이내)
  res.status(200).send('OK');
});

app.listen(3000);

2단계: 웹훅 URL 등록

대시보드 또는 API로 웹훅 URL을 등록합니다.

POST https://api.deliveryapi.co.kr/v1/webhooks

{
  "url": "https://yourdomain.com/webhooks/delivery",
  "events": [
    "delivery.picked_up",
    "delivery.in_transit",
    "delivery.delivered"
  ]
}

웹훅 이벤트 타입

보안: 시그니처 검증

웹훅 요청이 DeliveryAPI에서 온 것인지 검증해야 합니다.

const crypto = require('crypto');

function verifySignature(req) {
  const signature = req.headers['x-deliveryapi-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.WEBHOOK_SECRET;
  
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === hash;
}

app.post('/webhooks/delivery', (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // 웹훅 처리...
});

재시도 로직

여러분의 서버가 응답하지 않으면 자동으로 재시도합니다.

✅ 베스트 프랙티스
• 3초 이내에 200 응답 반환
• 무거운 작업은 백그라운드로 처리
• 중복 이벤트 처리 (idempotency)
• 로그 기록

다음 단계