웹훅을 사용한 stablecoin 결제 정산 자동화 방법 (developer runbook)

Source: Dev.to

Webhooks와 결정적 ID를 활용한 스테이블코인 결제 자동 조정

이미 Web2 백엔드가 구축돼 있고 수동 암호화폐 조정을 피하고 싶다면, 다음과 같은 실용적인 흐름을 사용할 수 있습니다:

1. 체크아웃(결제 링크) 생성
2. Webhook 이벤트 수신 (payment.created, payment.confirmed, payment.rejected)
3. 감사를 위한 주문 증명 조회
4. 내부 DB에 결정적 원장 키 기록

리소스

• GitHub 스타터 팩
• Postman 문서

10분 안에 API 흐름 실행하기 (Postman)

다음 파일들을 Postman에 임포트하세요

• NUVO-Verify-Developer-Inbound.postman_collection.json
• NUVO-Verify-Sandbox.postman_environment.json

그 다음 순서를 실행합니다

1. 가맹점 로그인
2. 결제 링크 생성
3. Webhook 생성
4. 테스트 Webhook 전송
5. 주문 증명 조회

샘플 Webhook 핸들러 (Node.js)

import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.raw({ type: "*/*" }));

const WEBHOOK_SECRET = process.env.NUVO_WEBHOOK_SECRET;

function verifySignature(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signatureHeader || "");
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhooks/nuvo", (req, res) => {
  const sig =
    req.header("x-nuvo-signature") ||
    req.header("x-signature") ||
    "";
  if (!verifySignature(req.body, sig, WEBHOOK_SECRET)) {
    return res.status(401).json({ ok: false, error: "invalid signature" });
  }

  const payload = JSON.parse(req.body.toString("utf8"));
  const ledgerKey = `${payload?.data?.orderId}:${payload?.data?.tokenSymbol}:${payload?.event}`;

  // upsert to your internal ledger table
  // upsertLedger({ ledgerKey, payload });

  return res.json({ ok: true });
});

app.listen(8787, () => console.log("listening on :8787"));

권장 최소 테이블 필드

핵심 정리

• 거래별 수동 매칭이 필요 없습니다.
• 결정적 키를 사용해 중복 전송을 방지합니다.
• 증명 엔드포인트를 통해 완료된 주문에 대한 감사 가능한 증거를 제공합니다.
• 기존 Web2 백엔드를 유지하면서, idempotent(멱등) 기록자를 갖춘 Webhook 엔드포인트만 추가하면 됩니다.
• 샌드박스 환경에서 시작한 뒤 프로덕션으로 전환하세요.