网络网络即时收到签名活动

有效载荷的格式

所有交付共享相同的顶级 JSON 架构：`event`、`data` 和 `timestamp`。事件名称也在 `X-Certyneo-Event` 标头中重复，这允许在解析请求体之前进行路由。`data` 的内容因事件而异，但始终是简单值的平面对象——永远没有数组或嵌套对象。以下是完整的 `envelope.completed` 交付。

POST /webhooks/certyneo HTTP/1.1
Host: your.app
Content-Type: application/json
X-Certyneo-Event: envelope.completed
X-Certyneo-Delivery-Id: cm8f2h6a10004qr9k5p2wm3xt
X-Certyneo-Signature: 4f3d1c8b2a9e7f60d5c4b3a2918e7f6d5c4b3a2918e7f6d5c4b3a2918e7f6d5c

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "sandbox": false,
    "subject": "Contrat de prestation Acme Corp",
    "status": "COMPLETED",
    "signatureLevel": "ADVANCED",
    "aesSignerCount": 2,
    "completedAt": "2026-05-27T08:42:13.000Z",
    "recipientCount": 2,
    "recipients": [
      { "email": "alice@acme.com", "name": "Alice Martin", "role": "SIGNER", "status": "SIGNED" },
      { "email": "bob@acme.com", "name": "Bob Durand", "role": "SIGNER", "status": "SIGNED" }
    ],
    "fieldValues": [
      { "fieldId": "cm7x2k9p40005qz8h1a2b3c4d", "fieldType": "RADIO_GROUP", "recipientEmail": "alice@acme.com", "value": "Option B" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/cm7x2k9p4.../contrat.pdf?X-Amz-Expires=604800&X-Amz-Signature=..."
  },
  "timestamp": "2026-05-27T08:42:13.521Z"
}

signedDocumentUrl 是一个从事件开始有效期为 7 天的预签名链接：它避免了第二次身份验证调用来检索 PDF。如果预签名失败，或在没有存储文件的已完成 QES 信封上，则不存在该链接——而不是 null；此时请重新使用 GET /v1/envelopes/id/signed-document，这仍然是真实来源。还要注意，在事件发生 7 天后从死信队列手动重放：负载中的链接已过期，API 端点没有过期。

收件符号是UTF-8编码,没有BOM.HMAC签名计算在原始体内,如发送不要改变空格,JSON重新解析经常改变密钥的顺序,破坏验证.

检查HMAC的签名

每个请求都使用您的webhook密钥签名（在创建订阅时仅显示一次）。签名在`X-Certyneo-Signature`请求头中传输：这是请求原始正文的HMAC-SHA256，以十六进制编码，不带前缀或时间戳。处理payload前请ALWAYS验证签名——没有这一步骤，任何人都可以伪造事件并调用您的端点。

import crypto from "node:crypto";

export function verifyCertyneoSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  // X-Certyneo-Signature = HMAC-SHA256(secret, rawBody), hex-encoded.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = Buffer.from(signatureHeader, "hex");
  const computed = Buffer.from(expected, "hex");

  // timingSafeEqual throws when the two buffers differ in length —
  // a malformed header must return false, not crash the handler.
  if (received.length !== computed.length) return false;

  // timingSafeEqual to mitigate timing attacks.
  return crypto.timingSafeEqual(computed, received);
}

import hashlib
import hmac


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

    `X-Certyneo-Signature` holds the hex-encoded HMAC-SHA256 of the
    raw request body, computed with your webhook secret.
    """
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature_header)

试用政策

如果您的端点响应耗时过长、拒绝连接或返回5xx（或429），我们将按指数退避重试：总共5次尝试，耗时约1小时20分。第五次后，事件进入死信队列——可从您的仪表板查询和重放，但不再自动重试。明确拒绝（401、403、404、410、422…）则从不重试：响应不会改变，事件直接进入死信队列。

指定的延迟时间是最小值：重试扫描由cron控制，因此重试可能会在理论时间之后稍微才开始。放弃的事件列在Webhooks → 失败中，带有手动重放按钮且无保留期限。连续失败五次的端点——或响应404/410的端点——会自动停用，您将收到电子邮件通知：修正后重新激活，计数器重置为零（任何成功交付也会将其重置为零）。

试验没有发送真正的信封

首先创建一个订阅——响应包含HMAC验证所需的`secret`，仅显示一次。从设置 → Webhooks，「测试」按钮随后会发送一个签名的POST，完全像真实交付一样，并显示您服务器的原始响应：这是验证您的处理程序的最快方式，通过ngrok在本地或在持续集成中进行。

# Create a subscription — "secret" is returned once, store it now.
curl -X POST https://api.certyneo.com/v1/webhooks \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your.app/webhooks/certyneo",
    "events": ["envelope.completed", "recipient.signed"]
  }'

URL必须在HTTPS上公开可访问：私有地址或localhost会在创建订阅时被SSRF保护拒绝。

订阅按环境隔离，就像密钥一样：使用 sk_test_ 密钥创建的 webhook 仅接收测试信封的事件，使用 sk_live_ 密钥创建的 webhook 仅接收真实信封的事件。因此，测试信封永远不会到达您的生产 URL，每个负载都指示"sandbox"（true 或 false）。

为了更进一步

• 开发者中心
• 电子签名API
• 美国原住民
• 安全页面
• 计划和费用