Webhooks να λαμβάνετε τα γεγονότα υπογραφής σε πραγματικό χρόνο

Φόρμα του φορτίου

Όλες οι παραδόσεις μοιράζονται το ίδιο σχήμα 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 ημέρες από το γεγονός: αποφεύγει μια δεύτερη αυθεντικευμένη κλήση για ανάκτηση του PDF. Απουσιάζει — και όχι null — εάν η προ-υπογραφή απέτυχε ή σε έναν φάκελο QES που ολοκληρώθηκε χωρίς αποθηκευμένο έγγραφο. Στη συνέχεια, επιστρέψτε στο GET /v1/envelopes/id/signed-document, η οποία παραμένει η πηγή της αλήθειας. Προσοχή και στην χειροκίνητη αναπαραγωγή από την dead-letter queue περισσότερο από 7 ημέρες μετά το γεγονός: ο σύνδεσμος του φορτίου έληξε, το API endpoint όχι.

Το payload είναι κωδικοποιημένο σε UTF-8, χωρίς BOM. Η υπογραφή HMAC υπολογίζεται στο πρωτότυπο σώμα όπως αποστέλλεται μην αλλοιώνετε τα κενά, η επαναπαραγραφή JSON συχνά αλλάζει την σειρά των κλειδιών και σπάει την επαλήθευση.

Ελέγξτε την υπογραφή HMAC

Κάθε αίτημα υπογράφεται με το μυστικό σας webhook (εμφανίζεται μόνο μία φορά κατά τη δημιουργία της συνδρομής). Η υπογραφή μεταδίδεται στην κεφαλίδα `X-Certyneo-Signature`: είναι το HMAC-SHA256 του ακατέργαστου σώματος του αιτήματος, κωδικοποιημένο σε δεκαεξαδικό, χωρίς πρόθεμα ή χρονόσημο. Επαληθεύστε ΠΑΝΤΑ την υπογραφή πριν επεξεργαστείτε το payload — χωρίς αυτό το βήμα, οποιοσδήποτε μπορεί να πλαστογραφήσει ένα γεγονός και να καλέσει το 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)

Πολιτική επαναπροσδιορισμού

Εάν το endpoint σας χρειάζεται πολύ χρόνο για να ανταποκριθεί, αρνείται τη σύνδεση ή επιστρέφει 5xx (ή 429), γίνεται νέα προσπάθεια σύμφωνα με εκθετική υποχώρηση: 5 προσπάθειες συνολικά, σε περίπου 1 ώρα 20 λεπτά. Μετά την πέμπτη, το συμβάν μεταβαίνει σε dead-letter queue — διαθέσιμο και αναπαραγόμενο από το dashboard σας, αλλά δεν γίνεται νέα αυτόματη προσπάθεια. Μια ρητή άρνηση (401, 403, 404, 410, 422...) δεν γίνεται ποτέ νέα προσπάθεια: η απάντηση δεν θα άλλαζε, το συμβάν μεταβαίνει απευθείας στη dead-letter queue.

Οι αναφερόμενες καθυστερήσεις είναι ελάχιστες: η σάρωση επανάληψης ελέγχεται από ένα cron, επομένως μια προσπάθεια μπορεί να ξεκινήσει ελαφρώς μετά τη θεωρητική ώρα. Τα εγκαταλελειμμένα συμβάντα παρατίθενται στο Webhooks → Αποτυχίες, με κουμπί χειροκίνητης αναπαραγωγής και χωρίς περιορισμό διάρκειας διατήρησης. Ένα endpoint που έχει πέντε διαδοχικές οριστικές αποτυχίες — ή που ανταποκρίνεται με 404 / 410 — απενεργοποιείται αυτόματα και λαμβάνετε ειδοποίηση μέσω email: επανενεργοποιήστε το μόλις διορθωθεί, ο μετρητής ξεκινά από το μηδέν (οποιαδήποτε επιτυχής παράδοση το επανατοποθετεί επίσης στο μηδέν).

Δοκιμασία χωρίς να στείλετε πραγματικό φάκελο

Δημιουργήστε πρώτα μια συνδρομή — η απάντηση περιέχει το `secret` που απαιτείται για την επαλήθευση HMAC, εμφανίζεται μόνο μία φορά. Από τα Ρυθμίσεις → Webhooks, το κουμπί « Δοκιμή » στέλνει στη συνέχεια ένα υπογεγραμμένο POST ακριβώς όπως μια πραγματική παράδοση και σας εμφανίζει την ακατέργαστη απάντηση του διακομιστή σας: αυτός είναι ο ταχύτερος τρόπος για να επικυρώσετε το handler σας, τοπικά μέσω 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 κατά τη δημιουργία της συνδρομής.

Οι συνδρομές είναι διαχωρισμένες ανά περιβάλλον, όπως και τα κλειδιά: ένα webhook δημιουργημένο με κλειδί sk_test_ λαμβάνει μόνο γεγονότα φακέλων δοκιμής, ένα webhook δημιουργημένο με κλειδί sk_live_ μόνο γεγονότα φακέλων παραγωγής. Ένας φάκελος δοκιμής δεν φτάνει ποτέ στη URL παραγωγής σας, και κάθε φορτίο πληροφοριών υποδεικνύει «sandbox» (true ή false).

Για να πάμε πιο πέρα

• Επικεφαλής
• Ηλεκτρονική υπογραφή API
• Γενικές ενσωματώσεις
• Ασφαλής σελίδα
• Σχέδια και τιμές