알림톡 웹훅 설정

발송 결과를 폴링하지 않고 받으려면 웹훅을 걸어요. 수신 URL 과 구독할 이벤트를 지정하면 상태가 확정될 때 부트페이가 요청을 보내요.

1설정 조회

코드 예제

curl -X GET "https://message.bootapi.com/alimtalk/webhook" \
  -H "Authorization: Basic {base64(client_key:secret_key)}"bash

require 'bootpay'

commerce = BootpayStore::RestClient.new(client_key: 'your-commerce-client-key', secret_key: 'your-commerce-secret-key')
response = commerce.alimtalk_webhook_detail
puts response.dataruby

응답

아직 설정하지 않았다면 configured: false 만 내려와요.

{
  "configured": true,
  "url": "https://example.com/hooks/alimtalk",
  "events": [301, 302, 303, 310, 311],
  "enabled": true,
  "secret": "whsec_1a2b3c********",
  "last_sent_at": "2026-08-27T10:00:05+09:00",
  "last_status": 200,
  "consecutive_failures": 0,
  "auto_disabled_at": null,
  "retry_count": 10
}json

retry_count 는 수신 서버가 2xx 를 돌려주지 않을 때 건마다 최대 몇 번까지 보낼지​​예요(첫 전송 포함, 기본 10). 아래 2. 설정 저장​​에서 바꿀 수 있어요.

시크릿은 앞 12자만 보여요. 원문은 시크릿 재발급 응답에서만 볼 수 있어요. 시각 필드 형식은 응답의 시각 형식을 봐요.

2설정 저장

요청 파라미터

최초 저장 시 서명 시크릿이 자동 발급돼요.

retry_count 는 저장한 뒤 새로 만들어지는 전송 건​​부터 적용돼요. 이미 큐에 있는 건은 만들어질 때의 횟수를 따라요.

이벤트 코드 (events)

events 배열에 넣는 값이에요. enum 키가 아니라 숫자 그대로 주고받아요.

접수(300)와 발송 제외 등록(320)은 건당 발화라 노이즈가 커서 명시적으로 구독해야만 발송돼요. 목록에 없는 값은 저장할 때 조용히 버려져요.

코드 예제

curl -X PUT "https://message.bootapi.com/alimtalk/webhook" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/alimtalk",
    "events": [301, 302, 303, 310, 311],
    "enabled": true,
    "retry_count": 5
  }'bash

response = commerce.alimtalk_webhook_update(
  url: 'https://example.com/hooks/alimtalk',
  events: [301, 302, 303, 310, 311],
  enabled: true,
  retry_count: 5
)
puts response.dataruby

서명 검증

요청에 아래 헤더가 붙어요.

X-Bootpay-Webhook-Event: alimtalk.send.succeeded
X-Bootpay-Delivery-Id: 68b0f2a1c3d4e5f6a7b8c9e1
X-Bootpay-Timestamp: 1756272000
X-Bootpay-Signature: sha256=HMAC_SHA256(secret, "{X-Bootpay-Timestamp}.{raw_body}")

수신 서버에서 같은 방식으로 계산해 비교하고, 타임스탬프가 5분 이상 지난 요청은 거부​​해요(replay 방지). 서명은 파싱하기 전 원본 본문(raw body) 으로 계산해요. sha256= 뒤의 값은 HMAC-SHA256 결과를 소문자 16진수(hex)로 적은 것이에요. X-Bootpay-Delivery-Id 는 전송 이력의 delivery_id 와 같아요.

payload

본문은 아래 봉투에 이벤트별 data 가 담긴 모양이에요.

발송 이벤트(301·302·303)의 data 는 발송내역 목록의 항목과 같은 카드예요. 그래서 조회·목록·웹훅을 파서 하나로 처리할 수 있어요. 다만 시각 필드는 웹훅에서 ISO8601 로 와서 REST 응답과 형식이 달라요 — 응답의 시각 형식을 봐요.

검수 이벤트(310·311)의 data 예요.

발송 제외 등록 이벤트(320)의 data 예요.

자동 비활성

연속 실패가 10회(기본값)에 이르면 웹훅이 자동으로 비활성화​​돼요. 죽은 URL 로 영원히 재시도하지 않기 위해서예요. 실패는 수신 서버가 2xx 가 아닌 HTTP 응답을 돌려준 경우만 세고, 재시도도 한 번씩 세요. 연결 실패·타임아웃처럼 응답 자체가 없으면 세지 않아서 자동 비활성이 걸리지 않아요.

auto_disabled_at 에 시각이 찍히고, URL 을 고쳐 다시 저장하면 실패 카운터와 auto_disabled_at 이 초기화돼요. 이때 enabled 는 false 로 남으니 다시 받으려면 enabled: true 를 함께 보내요.

발송 요청에 실은 webhook_url 의 실패는 이 카운터에 들어가지 않아요. 그 주소가 죽어 있어도 여기 저장한 수신 URL 은 그대로 살아 있어요(주소가 서로 같을 때만 함께 세요). 대신 건별 주소에는 자동 비활성이 없으니, 주소를 바꿀 때는 발송 요청 쪽을 고쳐요.

에러 코드

다음 단계

설정을 마쳤다면 테스트 발송으로 수신 서버가 제대로 받는지 확인해요.