Webhooks přijímat signály v reálném čase

Formát užitečného zatížení

Všechna doručení sdílejí stejné schéma JSON na nejvyšší úrovni: `event`, `data` a `timestamp`. Název události se také opakuje v hlavičce `X-Certyneo-Event`, která umožňuje směrování ještě před analýzou těla. Obsah `data` se liší v závislosti na události, ale zůstává vždy plochý objekt s jednoduchými hodnotami — nikdy pole ani vnořený objekt. Zde je úplné doručení `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 je předem podepsaný odkaz platný 7 dní od události: vyhýbá se druhému ověřenému volání pro načtení PDF. Chybí — a není null — pokud se předběžné podepisování nezdařilo, nebo na obálce QES dokončené bez uloženého dokumentu; poté přejděte na GET /v1/envelopes/id/signed-document, který zůstává zdrojem pravdy. Pozor také na ruční přehrávání z fronty mrtvých dopisů více než 7 dní po události: odkaz v payloadu je vypršel, koncový bod API nikoli.

HMAC podpis je vypočítán na hrubém těle, jak byl odeslán.

Zkontrolujte podpis HMAC

Každý požadavek je podepsán vaším webhooku secret (zobrazen pouze jednou při vytvoření předplatného). Podpis se přenáší v hlavičce `X-Certyneo-Signature` : jedná se o HMAC-SHA256 nezpracovaného těla požadavku, zakódovaného v hexadecimální podobě, bez předpony nebo časového razítka. VŽDY ověřte podpis před zpracováním payloadu — bez tohoto kroku si kdokoli může vymyslet událost a zavolat váš endpoint.

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)

Zkouška

Pokud váš endpoint trvá příliš dlouho na odpověď, odmítne připojení nebo vrátí 5xx (nebo 429), opakujeme podle exponenciálního zpětného postihu: 5 pokusů celkem, přibližně za 1 h 20. Po pátém pokusu se událost přesune do fronty dead-letter — zobrazitelná a přehrávatelná z vašeho panelu, ale již se automaticky neopakuje. Explicitní odmítnutí (401, 403, 404, 410, 422…) se naopak nikdy neopakuje: odpověď by se neměnila, událost jde přímo do fronty dead-letter.

Uvedené časy jsou minimální: kontrola opakování je řízena cronem, pokus tedy může vyjít mírně později než teoretický čas. Opuštěné události jsou uvedeny v sekci Webhooks → Selhání, s tlačítkem ruční přehrávky a bez omezení doby uchovávání. Endpoint, který selže pětkrát za sebou — nebo který vrátí 404 / 410 — je automaticky deaktivován a budete o tom informováni e-mailem: znovu jej aktivujte po opravě, čítač se vrátí na nulu (každé úspěšné doručení jej také vrátí na nulu).

Testování bez zaslání skutečné obálky

Nejprve vytvořte předplatné — odpověď obsahuje `secret` potřebný pro ověření HMAC, zobrazený pouze jednou. Z Nastavení → Webhooks potom tlačítko « Testovat » odešle podepsaný POST přesně jako skutečné doručení a zobrazí vám nezpracovanou odpověď vašeho serveru : je to nejrychlejší způsob, jak ověřit váš handler, místně přes ngrok nebo v rámci průběžné integrace.

# 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 musí být veřejně dostupná přes HTTPS : soukromá adresa nebo localhost je odmítnut ochranou SSRF při vytvoření předplatného.

Odběry jsou odděleny podle prostředí, stejně jako klíče: webhook vytvořený pomocí klíče sk_test_ přijímá pouze události z testovacích obálek, webhook vytvořený pomocí klíče sk_live_ pouze ty ze skutečných obálek. Testovací obálka se proto nikdy nedostane na vaši produkční URL a každá datová část označuje "sandbox" (true nebo false).

Pro další krok.

• Hub vývojář
• API elektronického podpisu
• Domorodé integrace
• Bezpečnostní stránka
• Plány a tarify