Webhooks saada realtime allkirjastamise sündmused

Kasuliku laeva suurus

Kõik sündmused jagavad sama JSONi tipptasemel šemaat: `event`, `envelope_id`, `occurred_at`, `data`.

{
  "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 allkiri arvutatakse kehalise keha kohta nii, nagu saadetud ei muuda ruume, JSON-i uuesti analüüsimine muudab sageli võtmete järjestust ja rikub kontrollimise.

Kontrolli HMAC allkirja

Iga päring allkirjastatakse teie webhooki salajasusega (nähtatav vaid üks kord, kui seda paneelile luuakse, seejärel on see endal salastatud).<timestamp>V1=<hex_hmac>Kontrollige alati allkirja enne laeva töötlemist. Ilma selle sammuna võib igaüks ürituse võltsida ja teie lõpppunkti kutsuda.

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)

Uurimispoliitika

Kui teie lõpppunkt vastab teisele kui HTTP 2xx (timeout, 5xx, connection refused) sõnumile, siis me helistame eksponentsiaalse tagasilükkamise järgi. Kokku 6 katset ~9 tunni jooksul. Pärast 6 üritust märgitakse sündmus `failed` teie veebisühenduse paneelil ja saadetakse hoiatus e-posti.

Kui soovite ebaõnnestunud toimetust käsitsi edastada, on veebisühenduse paneelil iga ebaõnnestunud toimetuse puhul nuppu Re-deliver , mis on kättesaadav 7 päeva jooksul pärast lõplikku ebaõnnestumist.

Proovida ilma päris ümbriku saatmata

Lõpppunkt `/v1/webhooks/test` võtab vastu URL-i ja sündmuse tüübi ning POSTeb fiktiivse payload, mis on allkirjastatud täpselt nagu tõeline.

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

Et minna edasi

• Arendaja hub
• Elektrooniline allkiri API
• Põlisrahvaste integreerumine
• Turvalehekülg
• Plaanid ja hinnad