Webhooks kapja meg a valós idejű aláírási eseményeket

Használati teher formátuma

Minden kézbesítés ugyanazt az top-level JSON sémát osztja: `event`, `data` és `timestamp`. Az esemény nevét a `X-Certyneo-Event` fejlécben is megismétlik, ami lehetővé teszi az útvonalválasztást még a test elemzése előtt. A `data` tartalma az esemény szerint változik, de mindig egy egyszerű értékek sík objektuma marad — soha nem tömb vagy beágyazott objektum. Íme egy teljes `envelope.completed` kézbesítés.

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

A signedDocumentUrl egy előre aláírt link, amely az eseménytől számított 7 napig érvényes: elkerüli a PDF lekéréséhez szükséges második hitelesített hívást. Hiányzik — és nem null —, ha az előaláírás meghiúsult, vagy ha egy QES-borítékot készítottek el tárolt dokumentum nélkül; használja helyette a GET /v1/envelopes/id/signed-document végpontot, amely a hiteles forrás. Ügyeljen arra is, hogy az eseménytől több mint 7 nappal később manuális újrajátszás után a dead-letter queue-ból: a payload-ban szereplő link lejárt, az API-végpont nem.

A HMAC aláírás a brutális testre számít, ahogy elküldtük ne változtassuk meg a réseket, a JSON újraparsolás gyakran megváltoztatja a kulcsok sorrendjét és megszakítja a hitelesítést.

Ellenőrizni a HMAC aláírást

Minden kérés alá van írva a webhook-titokkal (az előfizetés létrehozásakor csak egyszer jelenik meg). Az aláírás az `X-Certyneo-Signature` fejlécben kerül továbbításra: ez a kérés nyers törzse HMAC-SHA256, hexadecimálisan kódolva, előtag vagy időbélyeg nélkül. MINDIG ellenőrizze az aláírást a payload feldolgozása előtt — e lépés nélkül bárki hamisíthat egy eseményt és meghívhatja az Ön végpontját.

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)

Újrapróbálási politika

Ha az endpoint túl hosszú ideig válaszol, megtagadja a kapcsolatot vagy 5xx-et (vagy 429-et) ad vissza, exponenciális visszalépés szerint próbálkozunk újra: összesen 5 kísérlet, körülbelül 1 óra 20 perc alatt. Az ötödik után az esemény dead-letter queue-ba kerül — megtekinthető és újrajátszható az irányítópultról, de már nem próbálkozik meg automatikusan. Az explicit megtagadás (401, 403, 404, 410, 422…) viszont sohasem próbálkozik újra: a válasz nem változna meg, az esemény közvetlenül a dead-letter queue-ba kerül.

A feltüntetett határidők minimumok: az újrapróbálkozási vizsgálatot egy cron ütemezi, így a kísérlet az elméleti idő után néhány perccel indulhat el. Az elhagyott események a Webhooks → Hibák alatt találhatók, manuális újrajátszás gombbal és korlátlan megőrzési idővel. Az az endpoint, amely öt végzetes hibát láncolnak össze — vagy amely 404 / 410 -et válaszol — automatikusan letiltásra kerül, és e-mailben értesítést fog kapni: aktiválja újra a javítása után, a számláló nulláról indul (minden sikeres kézbesítés szintén nulláról indítja újra).

A valódi boríték elküldése nélkül tesztelni

Először hozzon létre egy előfizetést — a válasz tartalmazza az HMAC-ellenőrzéshez szükséges `secret`-et, amely csak egyszer jelenik meg. A Beállítások → Webhookok menüből a "Teszt" gomb ezután olyan POST-ot küld, amely pontosan olyan aláírt, mint a valódi kézbesítés, és megjeleníti a szerver nyers válaszát: ez a leggyorsabb módja a kezelő validálásának, lokálisan az ngrok-on vagy a folyamatos integrációban.

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

Az URL nyilvánosan elérhető HTTPS-en keresztül: egy privát cím vagy localhost az SSRF-védelemmel elutasított az előfizetés létrehozásakor.

Az előfizetések környezet szerint elkülönítve vannak, mint a kulcsok: egy sk_test_ kulccsal létrehozott webhook csak tesztborítékok eseményeit fogadja, egy sk_live_ kulccsal létrehozott webhook csak valós borítékok eseményeit. Egy tesztboríték tehát soha nem éri el az Ön üzemi URL-jét, és minden terhelés a "sandbox" jelzést tartalmazza (igaz vagy hamis).

Tovább kell mennünk.

• Hub fejlesztő
• E-aláírás API
• Az őslakos integrációk
• Biztonsági oldal
• Tervek és díjak