웹후크 실시간 서명 이벤트를 받습니다

페이로드 형식

모든 이벤트들은 같은 상위 레벨 JSON 패턴을 공유합니다: `event`, `envelope_id`, `occurred_at`, `data`. `data`의 내용은 이벤트에 따라 다릅니다.

{
  "event": "envelope.completed",
  "envelope_id": "env_01HG3K8X9Y2N4P5Q6R7S8T9V0W",
  "occurred_at": "2026-05-27T08:42:13.521Z",
  "data": {
    "title": "Contrat de prestation Acme Corp",
    "status": "completed",
    "created_at": "2026-05-24T14:12:00.000Z",
    "completed_at": "2026-05-27T08:42:13.000Z",
    "signers": [
      {
        "email": "client@acme.example",
        "name": "Alex Client",
        "signed_at": "2026-05-27T08:42:13.000Z",
        "method": "eidas_aes",
        "ip": "203.0.113.42"
      }
    ],
    "proof_pdf_url": "https://certyneo.com/api/envelopes/env_01HG.../proof.pdf"
  }
}

페이로드는 BOM 없이 UTF-8로 암호화된다. HMAC 서명은 전송된 바와 같이 의 원형에 계산된다.

HMAC 서명 확인

각 요청은 웹후크 비밀로 서명됩니다. (다시보드에서 생성할 때 한 번만 볼 수 있고, 휴식시엔 암호화됩니다.) 서명은 `Certyneo-Signature` 헤더에서 `t= 형식으로 전송됩니다.<timestamp>v1=<hex_hmac>`. 페이로드 처리 전에 항상 서명 확인하세요. 이 단계 없이는 누구나 이벤트를 만들어서 엔드포인트에 호출할 수 있습니다.

import crypto from "node:crypto";

export function verifyCertyneoSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  // Header format: t=<timestamp>,v1=<hex_hmac>
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=")),
  );
  const ts = parts.t;
  const sig = parts.v1;
  if (!ts || !sig) return false;

  // Reject events older than 5 minutes (replay protection).
  const age = Math.abs(Date.now() / 1000 - Number(ts));
  if (age > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  // timingSafeEqual to mitigate timing attacks.
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(sig, "hex"),
  );
}

import hashlib
import hmac
import time


def verify_certyneo_signature(
    raw_body: bytes, signature_header: str, secret: str
) -> bool:
    """Verify a Certyneo webhook signature.

    Header format: `t=<timestamp>,v1=<hex_hmac>`
    Rejects events older than 5 minutes (replay protection).
    """
    parts = dict(p.split("=") for p in signature_header.split(","))
    ts = parts.get("t")
    sig = parts.get("v1")
    if not ts or not sig:
        return False

    if abs(time.time() - int(ts)) > 300:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        f"{ts}.{raw_body.decode('utf-8')}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, sig)

재검토 정책

만약 여러분의 엔드포인트가 HTTP 2xx (시간정지, 5xx, 연결 거부) 를 제외한 다른 응답을 한다면, 우리는 기하급수적인 백업으로 응답합니다. 총 6번 ~9시간 동안 시도합니다. 6번을 마친 후에는 웹 탭에서 이벤트가 `실패`로 표시되고 경고 이메일이 전송됩니다.

만약 당신이 실패한 이벤트를 수동으로 전달하고 싶다면, 웹허크 대시보드에는 실패한 모든 배송에 대해 7일 동안 사용할 수 있는 재배송 버튼이 있습니다.

실제 봉투를 보내지 않고 테스트하는 것

엔드포인트 `/v1/webhooks/test`는 URL과 이벤트 타입을 받아, 실제와 정확히 서명된 가상의 페이로드를 POSTe합니다. 지속적인 통합 또는 로컬 개발 (ngrok 또는 동등한) 도중 핸들을 검증하는 데 이상적입니다.

# Trigger a test webhook to your endpoint
curl -X POST https://api.certyneo.com/v1/webhooks/test \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "envelope.completed", "url": "https://your.app/webhooks/certyneo"}'

더 나아가기 위해

• 개발자 허브
• 전자 서명 API
• 토착 통합
• 안전 페이지
• 계획과 요금