Webhooks — ricevi gli eventi di firma in tempo reale

Formato del payload

Tutte le consegne condividono lo stesso schema JSON di primo livello: `event`, `data` e `timestamp`. Il nome dell'evento è anche ripetuto nell'intestazione `X-Certyneo-Event`, il che consente il routing anche prima di analizzare il corpo. Il contenuto di `data` varia a seconda dell'evento, ma rimane sempre un oggetto piatto di valori semplici — mai un array né un oggetto annidato. Ecco una consegna `envelope.completed` completa.

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 è un link pre-firmato valido per 7 giorni a partire dall'evento: evita una seconda chiamata autenticata per recuperare il PDF. È assente — e non null — se la pre-firma non ha avuto esito positivo, o su una busta QES completata senza documento archiviato; torna allora a GET /v1/envelopes/id/signed-document, che rimane la fonte di verità. Fai attenzione anche alla riproduzione manuale dalla dead-letter queue più di 7 giorni dopo l'evento: il link nel payload è scaduto, l'endpoint API no.

Il payload è codificato UTF-8, senza BOM. La firma HMAC è calcolata sul body grezzo così come inviato — non alterate gli spazi, il re-parsing JSON spesso modifica l'ordine delle chiavi e rompe la verifica.

Verificare la firma HMAC

Ogni richiesta è firmata con il tuo segreto webhook (visualizzato una sola volta al momento della creazione della sottoscrizione). La firma è trasmessa nell'intestazione `X-Certyneo-Signature`: è l'HMAC-SHA256 del corpo grezzo della richiesta, codificato in esadecimale, senza prefisso né timestamp. Verifica SEMPRE la firma prima di elaborare il payload — senza questo passaggio, chiunque può falsificare un evento e chiamare il tuo 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)

Politica di retry

Se il vostro endpoint impiega troppo tempo a rispondere, rifiuta la connessione o restituisce un 5xx (o un 429), ritentiamo secondo un backoff esponenziale: 5 tentativi in totale, in circa 1 h 20. Dopo il quinto, l'evento finisce in dead-letter queue — consultabile e riproducibile dal vostro dashboard, ma non più ritentato automaticamente. Un rifiuto esplicito (401, 403, 404, 410, 422…) non è invece mai ritentato: la risposta non cambierebbe, l'evento finisce direttamente in dead-letter queue.

I tempi indicati sono minimi: la scansione di retry è cadenzata da un cron, quindi un tentativo può partire leggermente dopo l'ora teorica. Gli eventi abbandonati sono elencati in Webhooks → Errori, con un pulsante di riproduzione manuale e senza limite di durata di conservazione. Un endpoint che accumula cinque errori definitivi — o che risponde 404 / 410 — viene disabilitato automaticamente, e ne siete avvertiti via email: riabilitatelo una volta corretto, il contatore riparte da zero (qualsiasi consegna riuscita lo ripristina a zero).

Testare senza inviare una vera busta

Per prima cosa crea una sottoscrizione — la risposta contiene il `secret` necessario per la verifica HMAC, visualizzato una sola volta. Da Impostazioni → Webhooks, il pulsante « Test » invia quindi un POST firmato esattamente come una consegna reale e ti mostra la risposta grezza del tuo server: è il modo più veloce per convalidare il tuo gestore, localmente via ngrok o in integrazione continua.

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

L'URL deve essere raggiungibile pubblicamente in HTTPS: un indirizzo privato o localhost viene rifiutato dalla protezione SSRF al momento della creazione della sottoscrizione.

Gli abbonamenti sono separati per ambiente, come le chiavi: un webhook creato con una chiave sk_test_ riceve solo gli eventi delle buste di prova, uno creato con una chiave sk_live_ solo quelli delle buste reali. Una busta di prova non raggiunge quindi mai l'URL di produzione, e ogni payload indica «sandbox» (true o false).

Per approfondire

• Hub sviluppatore
• API firma elettronica
• Integrazioni native
• Pagina sicurezza
• Piani e tariffe