결과 Webhook

발송 결과가 확정되면 레드빈8 서버가 고객사가 등록한 URL 로 직접 HTTPS POST 합니다. 폴링 없이 결과를 실시간으로 반영할 수 있습니다.

설정

1. 결과 Webhook 메뉴에서 수신 URL 을 등록합니다.
2. 발급된 서명 시크릿(whsec_…)을 안전한 곳에 저장합니다. (원문은 발급 직후 한 번만 표시)
3. 테스트 전송 버튼으로 연결을 확인합니다. (webhook.test 이벤트)

수신 URL 조건

• https:// 만 가능하며 포트는 443 입니다. 유효한 TLS 인증서가 필요합니다.
• IP 주소 직접 지정, 사설망/내부망으로 해석되는 도메인, 사용자 정보(user:pass@)가 포함된 URL 은 등록할 수 없습니다.
• 리다이렉트(3xx)는 따라가지 않습니다. 최종 URL 을 등록하세요.

어떤 이벤트가 전송되나요?

• 최종 상태만 전송합니다. 중간 상태(SUBMITTED 등)는 보내지 않습니다.
• API 로 접수한 발송 건만 대상입니다. 웹 화면에서 발송한 건은 전송되지 않습니다.
• 수신자 1명당 최종 이벤트는 1회만 생성됩니다.

요청 형식

이벤트는 성능을 위해 최대 100건씩 묶어서 한 번의 POST 로 전송합니다.

헤더

본문

{
  "id": "dlv_75ca12ec-9e17-456a-8ee2-f770b512ed4f",
  "type": "message.batch",
  "created_at": "2026-11-07T09:00:06+09:00",
  "events": [
    {
      "event": "message.delivered",
      "message_id": 1374,
      "recipient_id": 3304886,
      "channel": "sms",
      "to": "01011112222",
      "status": "DELIVERED",
      "client_ref": "A-1001",
      "request_client_ref": "ship-20261107-am",
      "result": { "code": "4100", "message": "전달", "carrier": "SKT" },
      "delivered_at": "2026-11-07T09:00:05+09:00"
    },
    {
      "event": "message.failed",
      "message_id": 1374,
      "recipient_id": 3304887,
      "channel": "sms",
      "to": "01033334444",
      "status": "FAILED",
      "client_ref": "A-1002",
      "request_client_ref": "ship-20261107-am",
      "result": { "code": "4410", "message": "잘못된 번호", "carrier": null },
      "delivered_at": null
    }
  ]
}

결과 코드

events[].status 와 result.code 의 관계입니다. 조회 API(/v1/messages/{id}/recipients)의 result 도 같은 값을 사용합니다.

채널별 상세 결과 코드는 아래와 같습니다. 코드는 통신사·카카오 정책에 따라 추가될 수 있으므로, 모르는 코드는 status 로 성공/실패를 판단하고 message 를 그대로 표시하세요.

서명 검증 (필수)

요청이 레드빈8 에서 온 것인지 확인하려면 X-Redbean-Signature 를 검증하세요.

signature = "v1=" + hex( HMAC_SHA256( secret, timestamp + "." + raw_body ) )

• timestamp 는 X-Redbean-Timestamp 헤더 값, raw_body 는 파싱하기 전 원본 바이트입니다. (JSON 을 다시 직렬화하면 서명이 달라집니다)
• 비교는 상수 시간 비교(timing-safe)로 하세요.
• 재전송 공격을 막기 위해 timestamp 가 현재 시각과 5분 이상 차이나면 거부하세요.

import hmac, hashlib, time, json
from flask import Flask, request, abort

SECRET = "whsec_..."          # 환경변수/비밀 저장소에서 읽으세요
app = Flask(__name__)

@app.post("/redbean/webhook")
def webhook():
    raw = request.get_data()                     # 원본 바이트
    ts  = request.headers.get("X-Redbean-Timestamp", "")
    sig = request.headers.get("X-Redbean-Signature", "")

    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        abort(400)
    expected = "v1=" + hmac.new(SECRET.encode(), f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        abort(401)

    payload = json.loads(raw)
    for ev in payload["events"]:
        handle_event(ev)                         # event + recipient_id 로 멱등 처리
    return "", 200

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.REDBEAN_WEBHOOK_SECRET;
const app = express();

// 서명 검증을 위해 원본 바이트를 그대로 받습니다.
app.post("/redbean/webhook", express.raw({ type: "application/json", limit: "2mb" }), (req, res) => {
  const ts  = req.get("X-Redbean-Timestamp") ?? "";
  const sig = req.get("X-Redbean-Signature") ?? "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);

  const expected = "v1=" + crypto.createHmac("sha256", SECRET)
    .update(Buffer.concat([Buffer.from(ts + "."), req.body])).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(sig);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  for (const ev of JSON.parse(req.body.toString("utf8")).events) handleEvent(ev);
  res.sendStatus(200);
});

<?php
$secret = getenv('REDBEAN_WEBHOOK_SECRET');
$raw    = file_get_contents('php://input');           // 원본 바이트
$ts     = $_SERVER['HTTP_X_REDBEAN_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_X_REDBEAN_SIGNATURE'] ?? '';

if (!ctype_digit($ts) || abs(time() - (int)$ts) > 300) { http_response_code(400); exit; }

$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }

foreach (json_decode($raw, true)['events'] as $ev) {
    handleEvent($ev);                                  // event + recipient_id 로 멱등 처리
}
http_response_code(200);

응답 규칙

• 2xx 응답이면 성공으로 처리합니다. 응답 본문은 무시합니다.
• 연결 3초, 응답 10초 이내에 응답해야 합니다. 무거운 처리는 큐에 넣고 즉시 200 을 반환하세요.
• 2xx 가 아니거나 시간 초과·연결 오류면 실패로 보고 재시도합니다.

재시도와 중복 수신

• 같은 이벤트가 중복 전달될 수 있습니다(at-least-once). event + recipient_id 로 멱등 처리하세요.
• 전달 순서는 보장되지 않습니다. 상태 비교가 필요하면 조회 API 로 최종 상태를 확인하세요.
• 수신 서버 장애로 연속 50회 실패하면 Webhook 이 일시 중지(PAUSED) 됩니다. 이벤트는 보존되며, 서버를 복구한 뒤 Webhook 관리에서 재개하면 밀린 이벤트가 전송됩니다.

시크릿 교체

Webhook 관리에서 시크릿을 재발급하면 즉시 새 시크릿으로 서명됩니다. 수신 서버의 시크릿을 먼저 준비한 뒤 재발급하세요. 새 시크릿 원문은 재발급 직후 한 번만 표시됩니다.

보안 권장사항

• 서명 검증을 반드시 구현하세요. URL 만 알면 누구나 요청을 보낼 수 있습니다.
• 수신 엔드포인트에 별도 인증 정보를 URL 로 노출하지 마세요. (예: ?token=) 로그에 남을 수 있습니다.
• 방화벽에서 IP 를 제한해야 한다면 고객센터에 발신 IP 대역을 문의하세요.