Webhooks vastaanottaa allekirjoitustapahtumat reaaliajassa

Palveluvaraston muoto

Kaikilla toiminnoilla on sama ylin JSON-kaavio: `event`, `data` ja `timestamp`. Tapahtuman nimi toistetaan myös `X-Certyneo-Event`-otsikossa, mikä mahdollistaa reitityksen jo ennen tekstin jäsentämistä. `data`-sisältö vaihtelee tapahtuman mukaan, mutta on aina litteä objekti yksinkertaisista arvoista — ei koskaan taulukkoa eikä sisäkkäistä objektia. Tässä on täydellinen `envelope.completed`-toiminto.

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 on ennalta allekirjoitettu linkki, joka on voimassa 7 päivää tapahtumasta lähtien: se välttää toisen todentavan puhelun PDF:n hakemiseksi. Se puuttuu — eikä ole null — jos ennakkoallekirjoitus epäonnistui tai QES-kirjekuoressa, joka on täytetty ilman tallennettua asiakirjaa; palaa siihen GET /v1/envelopes/id/signed-document, joka on totuuden lähde. Huomio myös manuaalisesta uudelleenyrityksen takia dead-letter jonosta yli 7 päivää tapahtuman jälkeen: payload-linkki on vanhentunut, API-päätepiste ei.

HMAC-signaatti lasketaan raaka-ainetta vastaan älä muuta väliä, JSON-re-parsing muuttaa usein avainten järjestystä ja rikkoo tarkistuksen.

Tarkista HMAC-sääntö

Jokainen pyyntö allekirjoitetaan webhook-salaisuudellasi (näytetään vain kerran tilauksen luomisen yhteydessä). Allekirjoitus välitetään `X-Certyneo-Signature` -otsikossa: se on pyynnön raakarunko HMAC-SHA256, koodattu heksadesimaalilla, ilman etuliitettä tai aikaleimaa. Tarkista AINA allekirjoitus ennen payload-käsittelyä — ilman tätä vaihetta kuka tahansa voi väärentää tapahtuman ja kutsua päätepistettäsi.

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)

Uudelleenkäsittelypolitiikka

Jos endpoint-palvelusi vastaa liian hitaasti, kieltää yhteyden tai palauttaa 5xx-virheen (tai 429-koodin), yritämme uudelleen eksponentiaalisella backoff-strategialla: yhteensä 5 yritystä noin 1 h 20 minuutissa. Viidennen yrityksen jälkeen tapahtuma siirtyy dead-letter jonoon — se on nähtävissä ja toistettavissa kojelaustasi, mutta sitä ei enää uudelleen yritetä automaattisesti. Eksplisiittinen kieltäytyminen (401, 403, 404, 410, 422 jne.) ei sitä vastoin ole koskaan uudelleen yritetty: vastaus ei muuttuisi, tapahtuma siirtyy suoraan dead-letter jonoon.

Ilmoitetut aikarajat ovat minimeja: retry-skannaus on cron-aikaistettu, joten yritys voi lähteä hieman teoreetista aikaa myöhemmin. Hylätyt tapahtumat on lueteltu kohdassa Webhooks → Virheet, joissa on manuaalisen toiston painike ja rajoittamaton säilytysaika. Endpoint, joka epäonnistuu viisi kertaa peräkkäin – tai vastaa 404/410 – poistetaan käytöstä automaattisesti ja saat siitä ilmoituksen sähköpostilla: aktivoi se uudelleen korjaamisen jälkeen, laskuri nollautuu (mikä tahansa onnistunut toimitus nollaa sen myös).

Testaus ilman oikeaa kirjekuorta

Luo ensin tilaus — vastaus sisältää `secret`-avain, joka on tarpeen HMAC-verifiointiin ja näytetään vain kerran. Asetuksista → Webhooks -painikkeesta « Testaa » lähettää POST-pyynnön, joka on allekirjoitettu täsmälleen kuin todellinen toimitus, ja näyttää palvelimesi raakavastauksen: se on nopein tapa vahvistaa käsittelijäsi, paikallisesti ngrok:n kautta tai jatkuvassa integraatiossa.

# 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:n on oltava julkisesti saavutettavissa HTTPS:n kautta: yksityinen osoite tai localhost hylätään SSRF-suojauksella tilauksen luomisen yhteydessä.

Tilaukset erotetaan ympäristöittäin kuten avaimet: sk_test_-avaimella luotu webhook vastaanottaa vain testikuorien tapahtumia, sk_live_-avaimella luotu webhook vain todellisten kirjekuorien tapahtumia. Testikuori ei siis koskaan saavuta tuotanto-URL-osoitettasi, ja jokainen hyötykuorma ilmoittaa "sandbox" (true tai false).

Lue lisää

• Kehittäjähub
• Sähköinen allekirjoitus API
• Kotimaiset yhdentymiset
• Turvasivu
• Suunnitelmat ja hinnat