가이드

웹훅

AutoTransPay 웹훅 가이드입니다. 이벤트 종류, 요청 헤더와 서명 검증, 응답 규약, 재시도, 멱등 처리와 놓친 전송을 다시 맞추는 대사 방법을 설명합니다.

입금이 확정되거나 사람 확인이 필요해지면, AutoTransPay 가 가맹점 서버로 서명된 HTTP POST 를 보냅니다. 가맹점은 폴링 없이 웹훅 하나로 주문을 결제 완료 처리할 수 있습니다.

엔드포인트 등록

콘솔 → 개발자 → 웹훅에서 등록합니다.

  • URL 은 https:// 공개 주소만 받습니다. 포트는 443·8443, 사설 IP·내부 도메인은 거부되고, URL 에 아이디·비밀번호를 넣을 수 없습니다.
  • 로컬 개발 서버는 터널을 설치하지 않아도 됩니다. 테스트 모드에서는 http://localhost:<포트>/…(또는 127.0.0.1) 주소를 그대로 등록할 수 있습니다. 오토페이 서버는 로컬 주소로 보낼 수 없으므로 이 엔드포인트는 꺼진 채(로컬 주소) 로 두고, AI 에이전트가 MCP get_webhook_request 로 받은 서명된 요청을 직접 로컬 서버에 보내 서명 검증·결제 완료 처리까지 시험합니다. 실제 전달 시험은 배포한 서버의 https 주소로 합니다.
  • 리다이렉트(3xx)는 따라가지 않고 실패로 처리합니다. 최종 주소를 등록하세요.
  • 엔드포인트는 모드별 5개까지 등록할 수 있습니다.
  • 테스트 모드와 운영 모드 엔드포인트는 따로 등록합니다. 테스트 이벤트는 테스트 엔드포인트로만, 운영 이벤트는 운영 엔드포인트로만 갑니다.
  • 구독할 이벤트를 고릅니다 (기본값 deposit.matched).
  • 등록하면 엔드포인트별 서명 키(whsec_…)가 발급됩니다. 콘솔에서 다시 확인하거나 재발급할 수 있습니다.
  • 테스트 전송 버튼은 서명된 ping 이벤트를 보내고, 응답 코드·소요 시간·응답 본문을 바로 보여 줍니다.

이벤트 종류

이벤트 발생 시점 가맹점이 할 일
deposit.matched 입금이 주문에 확정됨 (자동·수동 모두) 주문을 결제 완료로 변경
deposit.review_required 사람 확인이 필요한 입금 관리자 알림 (선택)
order.expired 주문이 만료됨 재고 복구·주문 취소 (선택)
ping 콘솔의 테스트 전송 2xx 응답만

모든 이벤트는 같은 겉모양을 가집니다.

필드 설명
id 이벤트 ID (evt_…). AutoTransPay-Event-Id 헤더와 같음
object "event"
type 이벤트 종류
livemode 운영/테스트
created_at 이벤트 생성 시각
data 이벤트별 내용 (아래)

deposit.matched

JSON
{
  "id": "evt_3f9a1c0e7b2d4e8f9a6b5c4d3e2f1a0b",
  "object": "event",
  "type": "deposit.matched",
  "livemode": true,
  "created_at": "2026-09-29T05:13:40.342+00:00",
  "data": {
    "order": {
      "id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07",
      "order_number": "ORD-1042",
      "amount": 122500,
      "depositor_name": "홍길동",
      "metadata": { "cart_id": "c_981" }
    },
    "deposit": {
      "id": "a3e1b7c2-4d5f-4a6b-8c9d-0e1f2a3b4c5d",
      "amount": 122500,
      "depositor_name": "홍길동",
      "bank_code": "WOORI",
      "occurred_at": "2026-09-28T14:14:00+00:00"
    },
    "match": { "method": "auto", "actor": null, "amount_matches": true }
  }
}
필드 설명
data.order 확정된 주문 (metadata 는 등록 때 넣은 값 그대로)
data.deposit 매칭된 입금. occurred_at 은 알림에 적힌 거래 시각(없으면 수신 시각)
data.match.method auto(자동확정) 또는 manual(사람이 확정)
data.match.actor 수동 확정한 주체. user:<id> · api_key:<id> · telegram:<id> · mcp:<id>, 자동이면 null
data.match.amount_matches 주문 금액과 입금액이 같은지. 수동 확정에서는 false 일 수 있음
주의

수동 확정은 금액이 달라도 가능합니다. 결제 완료 처리 전에 data.match.amount_matches 또는 data.deposit.amount 를 확인해 부분 입금을 걸러 내세요.

deposit.review_required

JSON
{
  "id": "evt_8c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f",
  "object": "event",
  "type": "deposit.review_required",
  "livemode": true,
  "created_at": "2026-09-29T06:02:11.918+00:00",
  "data": {
    "deposit": {
      "id": "0b7e6d5c-4a3b-4c2d-9e1f-8a7b6c5d4e3f",
      "amount": 50000,
      "depositor_name": "홍길동"
    },
    "reason": "ambiguous",
    "candidates": [
      {
        "order_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "order_number": "ORD-1051",
        "depositor_name": "홍길동",
        "amount": 50000,
        "score": 100,
        "amount_match": true,
        "reasons": ["이름:exact"]
      },
      {
        "order_id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
        "order_number": "ORD-1057",
        "depositor_name": "홍길동",
        "amount": 50000,
        "score": 100,
        "amount_match": true,
        "reasons": ["이름:exact"]
      }
    ]
  }
}

reason 값은 판정 표를 참고하세요.

입금 1건당 처음 확인 필요가 될 때 한 번 보냅니다. 나중에 주문이 등록돼 후보가 바뀌어도 다시 보내지 않습니다(알림 채널에는 바뀔 때마다 알립니다). 가맹점이 자기 규칙으로 정할 수 있으면 이 이벤트를 받고 바로 입금 수동 매칭(POST /deposits/:id/match)으로 확정하세요 — 예: 후보가 모두 같은 고객의 중복 주문이면 가장 최근 주문. 응답하기 전에 확정하면 알림 채널에는 확인 필요 대신 확정 알림만 갑니다.

order.expired

JSON
{
  "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "object": "event",
  "type": "order.expired",
  "livemode": true,
  "created_at": "2026-09-30T05:12:03.000+00:00",
  "data": {
    "order": { "id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07", "order_number": "ORD-1042", "amount": 122500 }
  }
}

만료된 주문에 나중에 입금이 들어오면 자동확정하지 않고 expired_order 사유로 사람 확인을 요청합니다.

요청 헤더

헤더 값
Content-Type application/json
User-Agent AutoTransPay-Webhook/1.0
AutoTransPay-Signature t=<unix 초>,v1=<서명>
AutoTransPay-Event-Id 이벤트 ID (evt_…)
AutoTransPay-Event-Type 이벤트 종류

서명 검증

서명은 HMAC-SHA256(서명 키, "<t>.<요청 본문 원문>") 의 16진수 문자열입니다.

  1. AutoTransPay-Signature 헤더를 , 로 나눠 t 와 v1 을 꺼냅니다.
  2. t 가 현재 시각과 5분(300초) 이상 차이 나면 거부합니다 (재전송 공격 방지).
  3. t + "." + 본문 원문 을 서명 키로 HMAC-SHA256 해 16진수로 만든 값과 v1 을 상수 시간 비교합니다.
위험

반드시 파싱하기 전의 본문 원문(바이트) 으로 검증하세요. JSON 을 파싱했다가 다시 직렬화하면 공백·키 순서·유니코드 이스케이프가 달라져 서명이 맞지 않습니다.

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.AUTOTRANSPAY_WEBHOOK_SECRET; // whsec_…

function verifySignature(rawBody, header, secret, toleranceSec = 300) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.trim().split('=')));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.json() 이 아니라 express.raw() 로 원문을 받습니다
app.post('/webhooks/autotranspay', express.raw({ type: 'application/json' }), async (req, res) => {
  const raw = req.body.toString('utf8');
  if (!verifySignature(raw, req.get('AutoTransPay-Signature'), SECRET)) {
    return res.status(400).send('invalid signature');
  }
  const event = JSON.parse(raw);

  // 이미 처리한 이벤트면 아무것도 하지 않고 200
  if (await alreadyProcessed(event.id)) return res.sendStatus(200);

  if (event.type === 'deposit.matched') {
    const { order, deposit } = event.data;
    await markOrderPaid(order.order_number, deposit.amount);
  }
  await markProcessed(event.id);
  res.sendStatus(200);
});
// pages/api/webhooks/autotranspay.ts
import crypto from 'crypto';
import type { NextApiRequest, NextApiResponse } from 'next';

// 원문 그대로 받아야 서명이 맞습니다
export const config = { api: { bodyParser: false } };

async function readRawBody(req: NextApiRequest): Promise<string> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
  return Buffer.concat(chunks).toString('utf8');
}

function verifySignature(raw: string, header: string | undefined, secret: string) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.trim().split('=')));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${raw}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') return res.status(405).end();
  const raw = await readRawBody(req);
  const header = req.headers['autotranspay-signature'] as string | undefined;
  if (!verifySignature(raw, header, process.env.AUTOTRANSPAY_WEBHOOK_SECRET!)) {
    return res.status(400).send('invalid signature');
  }
  const event = JSON.parse(raw);
  if (event.type === 'deposit.matched') {
    // 주문번호 기준으로 멱등하게 결제 완료 처리
    await markOrderPaid(event.data.order.order_number, event.id);
  }
  res.status(200).json({ received: true });
}
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["AUTOTRANSPAY_WEBHOOK_SECRET"].encode()


def verify_signature(raw: bytes, header: str | None, tolerance: int = 300) -> bool:
    if not header:
        return False
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if "v1" not in parts or abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])


@app.post("/webhooks/autotranspay")
def autotranspay_webhook():
    raw = request.get_data()  # 파싱 전 원문
    if not verify_signature(raw, request.headers.get("AutoTransPay-Signature")):
        abort(400)
    event = json.loads(raw)
    if event["type"] == "deposit.matched":
        mark_order_paid(event["data"]["order"]["order_number"], event["id"])
    return "", 200
<?php
$secret = getenv('AUTOTRANSPAY_WEBHOOK_SECRET');
$raw = file_get_contents('php://input'); // 파싱 전 원문
$header = $_SERVER['HTTP_AUTOTRANSPAY_SIGNATURE'] ?? '';

$parts = [];
foreach (explode(',', $header) as $kv) {
    [$k, $v] = array_pad(explode('=', trim($kv), 2), 2, '');
    $parts[$k] = $v;
}
$t = (int) ($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $raw, $secret);

if (!$t || abs(time() - $t) > 300 || !hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(400);
    exit('invalid signature');
}

$event = json_decode($raw, true);
if ($event['type'] === 'deposit.matched') {
    // 주문번호 기준으로 멱등하게 결제 완료 처리
    mark_order_paid($event['data']['order']['order_number'], $event['id']);
}
http_response_code(200);
팁

MCP 연동을 쓰면 AI 에이전트가 프로젝트의 프레임워크에 맞춰 이 코드를 직접 생성하고, ping 과 샌드박스 입금으로 끝까지 검증까지 해 줍니다.

응답 규약

AutoTransPay 는 응답 코드로 처리 결과를 판단합니다. 응답 본문은 해석하지 않습니다.

응답 의미 AutoTransPay 동작
2xx 받았음 전송 완료
409 · 410 · 422 이 입금확인을 거절함 (영구) 재시도하지 않음. deposit.matched 의 첫 전송이었다면 매칭을 되돌림
그 외 (4xx·5xx), 타임아웃, 연결 실패 일시 오류 재시도

deposit.matched 의 첫 전송을 409·410·422 로 거절하면:

  • 주문은 canceled, 입금은 review(review_reason: merchant_rejected)로 되돌아가고, 월 사용량에서도 빠집니다.
  • 조직 알림 채널(텔레그램 등)로 "가맹점 시스템이 입금확인을 거절했습니다" 알림이 갑니다. 이미 취소된 주문에 입금된 경우처럼 환불 검토가 필요한 상황에 쓰세요.

다음 경우에는 매칭을 유지하고 "확인 필요" 알림만 보냅니다. 앞선 전송이 이미 처리됐을 수 있기 때문입니다.

  • 재시도 중에 받은 거절 (첫 전송이 타임아웃 등으로 실패했지만 실제로는 처리됐을 수 있음)
  • 같은 이벤트를 다른 엔드포인트가 이미 2xx 로 받은 경우
  • 전송 전에 그 매칭이 이미 사람 손으로 취소·변경된 경우 (이 전송은 failed 로 끝납니다)
위험

중복 이벤트에 409 를 돌려주지 마세요. "이미 처리함"은 거절이 아니라 성공입니다. 중복 수신에 409 를 응답하면 정상적으로 결제된 주문의 매칭이 되돌려집니다. 중복은 항상 200 으로 응답하세요. 서명 검증 실패는 400(재시도 대상)으로 응답하세요.

요청 타임아웃은 10초입니다. 무거운 후속 작업(메일 발송, 재고 처리 등)은 큐에 넣고 먼저 200 을 응답하세요.

재시도

매칭이 확정되면 웹훅은 즉시 1차 전송됩니다. 실패하면 지수 백오프(30초 × 2^시도 횟수, 최대 6시간 간격)로 재시도하며, 첫 전송을 포함해 최대 12회 보냅니다.

시도 직전 실패 후 대기 첫 전송 후 경과(약)
1 — (즉시) 0
2 1분 1분
3 2분 3분
4 4분 7분
5 8분 15분
6 16분 31분
7 32분 1시간 3분
8 1시간 4분 2시간 7분
9 2시간 8분 4시간 15분
10 4시간 16분 8시간 31분
11 6시간 14시간 31분
12 6시간 20시간 31분
  • 재시도는 주기 작업이 처리하므로 실제 시각은 위 표보다 몇 분 늦을 수 있습니다.
  • 같은 엔드포인트가 3회 이상 연속 실패하고 15분 넘게 성공이 없으면 조직 알림 채널로 경보가 갑니다.
  • 12회 모두 실패하면 전송은 failed 가 됩니다. 콘솔 → 개발자 → 웹훅 → 전송 기록에서 failed 전송을 다시 보내기로 재전송할 수 있습니다.
  • 72시간 동안 성공 없이 실패만 이어진 엔드포인트는 자동으로 비활성화되고 알림이 갑니다. 서버를 고친 뒤 콘솔에서 다시 켜기 → 실패분 재전송(최근 72시간의 failed 전송을 한 번에 다시 보냄)을 누르세요. 그보다 오래된 이벤트는 이벤트 API로 대사하세요.
  • 엔드포인트가 비활성화되면 남은 전송은 failed 처리됩니다. 삭제하면 그 엔드포인트의 전송 기록도 함께 지워집니다.

멱등 처리

웹훅은 최소 한 번(at-least-once) 전송입니다. 가맹점이 200 을 응답했지만 네트워크 문제로 AutoTransPay 가 응답을 받지 못하면 같은 이벤트가 다시 옵니다.

  • AutoTransPay-Event-Id(= 본문 id)를 처리 기록에 저장하고, 이미 있으면 아무것도 하지 않고 200 을 응답하세요.
  • 또는 주문 상태로 멱등 처리하세요. "이미 결제 완료인 주문이면 건너뛴다"만으로도 충분합니다.
  • 이벤트는 순서가 뒤바뀌어 도착할 수 있습니다. 순서가 중요하면 created_at 을 비교하거나 주문 조회 API로 최신 상태를 확인하세요.

이벤트 API로 대사하기

웹훅 수신 서버가 오래 멈춰 있었다면, 이벤트 API 로 놓친 이벤트를 다시 가져와 처리할 수 있습니다. 하루 한 번 정도 대사 작업을 돌리는 것을 권장합니다.

Shell
curl "https://www.autotranspay.com/api/v1/events?type=deposit.matched&limit=100" \
  -H "Authorization: Bearer $AUTOTRANSPAY_API_KEY"

has_more 가 true 면, 응답의 next_cursor 를 starting_after 로 넘겨 다음 페이지를 가져옵니다 → 페이지네이션.

웹훅으로 받은 이벤트를 신뢰하기 전에 서버에서 한 번 더 확인하고 싶다면 GET /api/v1/events/{id}로 같은 이벤트를 조회할 수 있습니다.

서명 키 재발급

콘솔에서 서명 키를 재발급하면 즉시 새 키로 서명됩니다(이전 키와 겹치는 기간이 없습니다). 재발급 직후 새 키를 서버에 배포하세요. 그 사이 실패한 전송은 재시도되며, 새 키가 배포된 뒤 정상 처리됩니다.