Webhooks nhận các sự kiện đăng ký trong thời gian thực

Định dạng tải trọng

Tất cả các sự kiện đều chia sẻ cùng một kiểu JSON cấp cao: `event`, `envelope_id`, `occurred_at`, `data`. Nội dung của `data` khác nhau tùy theo sự kiện (các trường được ghi lại theo sự kiện trong tham chiếu API).

{
  "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"
  }
}

HMAC được tính trên body raw như đã gửi không thay đổi khoảng trống, việc phân tích lại JSON thường thay đổi thứ tự của các khóa và phá vỡ xác minh.

Kiểm tra chữ ký HMAC

Mỗi yêu cầu được ký bằng bí mật webhook của bạn (có thể nhìn thấy một lần khi tạo trong bảng điều khiển, sau đó được mã hóa khi nghỉ ngơi).<timestamp>,v1=<hex_hmac>`. Luôn luôn kiểm tra chữ ký trước khi xử lý payload không có bước này, bất cứ ai cũng có thể tạo ra một sự kiện và gọi đến điểm cuối của bạn.

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)

Chính sách thử lại

Nếu điểm cuối của bạn trả lời không phải là HTTP 2xx (timeout, 5xx, connection refused), chúng tôi sẽ quay lại theo cách sao lưu theo cấp số nhân. Tổng cộng 6 lần trong ~ 9 giờ. Sau 6 lần, sự kiện được đánh dấu là `failed` trong bảng điều khiển webhook của bạn và một email cảnh báo được gửi.

Nếu bạn muốn chuyển tiếp một sự kiện bị thất bại bằng tay, bảng điều khiển webhook cung cấp một nút Re-deliver trên mỗi giao hàng thất bại có sẵn trong 7 ngày sau khi thất bại cuối cùng.

Kiểm tra mà không gửi phong bì thật

Điểm cuối `/v1/webhooks/test` chấp nhận một URL và một loại sự kiện, và POSTe một payload giả ký giống như một thực.

# 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"}'

Để đi xa hơn

• Nhà phát triển Hub
• API chữ ký điện tử
• Sự kết hợp bản địa
• Trang an toàn
• Kế hoạch và giá