ウェブフック リアルタイムでサインアップイベントを受信

積載物の格式

すべての配信は同じトップレベル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" }
    ],
    "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日間有効な事前署名されたリンクです。認証されたAPIコールなしでPDFを取得できるため、2番目のコールを避けられます。事前署名に失敗した場合、またはドキュメントが保存されていないQES完了エンベロープ上の場合は、存在しません（nullではありません）。その場合は、GET /v1/envelopes/id/signed-documentを使用してください。これが信頼できるソースです。また、イベントから7日以上後に配信不可能キューから手動で再生した場合、ペイロード内のリンクは期限切れですが、APIエンドポイントはそうではないことに注意してください。

payload は UTF-8 でエンコードされ,BOM は含まれていない. HMAC 署名は送信されたままのボディ・ブルートに計算される. 空間を改変しないでください. JSON 再解析はしばしばキー順序を変更し,検証を破ります.

HMACの署名を確認する

各リクエストはWebhookシークレット（サブスクリプション作成時に1回だけ表示される）で署名されています。署名は`X-Certyneo-Signature`ヘッダーで送信されます。これは要求本文のHMAC-SHA256で、16進法でエンコードされており、接頭辞やタイムスタンプはありません。ペイロードを処理する前に、常に署名を検証してください。この検証なしに、誰でもイベントを偽造してエンドポイントを呼び出すことができます。

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分間。5番目の試行後、イベントはデッドレターキューに送られます—ダッシュボードから確認および再生可能ですが、自動再試行は行われません。明示的な拒否（401、403、404、410、422など）は再試行されません：応答は変わらないため、イベントはデッドレターキューに直接送られます。

表示されている期間は最小値です：再試行スキャンはcronによって制御されるため、試行は理論上の時刻の直後に開始される場合があります。放棄されたイベントはWebhooks→失敗にリストされ、手動再生ボタンがあり、保持期間に制限はありません。5つの決定的な失敗が連続したエンドポイント、または404/410で応答したエンドポイントは自動的に無効化され、メールで通知されます：修正後に再度有効化するとカウンターがゼロにリセットされます（配信に成功するたびにもゼロにリセットされます）。

試しに送るのに 本物の封筒を送らない

まずサブスクリプションを作成してください。応答にはHMAC検証に必要な`secret`が含まれており、1回だけ表示されます。設定→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
• ネイティブ統合
• セキュリティページ
• プランと料金