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 дни след събитието: връзката в payload е изтекла, API крайната точка не е.

Пайлоудът е кодиран UTF-8, без BOM. Подписът HMAC се изчислява върху грубото тяло, както е изпратено не променяйте пространствата, JSON ре-парсирането често променя реда на ключовете и нарушава проверката.

Проверка на HMAC подписа

Всяка заявка е подписана с вашата тайна на webhook (показана само веднъж при създаване на абонамента). Подписът се предава в заглавката `X-Certyneo-Signature` : това е HMAC-SHA256 на сурово тяло на заявката, кодирано в шестнадесетична система, без префикс или времеви печат. ВСЕГДА проверявайте подписа преди обработка на полезния товар — без тази стъпка всеки може да подправи събитие и да извика вашия крайна точка.

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)

Политика за повторни опити

Ако вашата крайна точка отнема твърде много време да отговори, откаже връзката или върне 5xx (или 429), ние повтаряме със експоненциален backoff: 5 опита общо, за приблизително 1 ч 20 мин. След петия, събитието отива в dead-letter queue — видимо и възпроизводимо от вашия панел управление, но вече не се повтаря автоматично. Явен отказ (401, 403, 404, 410, 422…) никога не се повтаря: отговорът не би се променил, събитието отива директно в dead-letter queue.

Посочените времеви периоди са минимални: сканирането на повторни опити е синхронизирано чрез cron, така че опитът може да се осъществи малко след теоретичното време. Напуснатите събития са в списък в Webhooks → Неуспехи, с бутон за ръчно възпроизвеждане и без ограничение на периода на съхранение. Крайна точка, която има пет последователни окончателни неуспеха — или която отговаря с 404 / 410 — се деактивира автоматично и вие сте уведомени по имейл: реактивирайте я след коригирането, счетчикът се върача към нула (всяко успешно доставяне също го връща към нула).

Изпитване без изпращане на истински плик

Първо създайте абонамент — отговорът съдържа `secret` необходимата за HMAC проверка, показана само веднъж. От Параметри → Webhooks бутонът « Тест » след това изпраща POST подписан точно като истинска доставка и ви показва сурова отговора от вашия сървър : това е най-бързия начин за валидиране на вашия обработчик, локално чрез 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 при създаване на абонамента.

Абонаментите са разделени по среда, както и ключовете : уеб кука, създадена с ключ sk_test_, получава само събитията от тестови пликове, уеб кука, създадена с ключ sk_live_, получава само събитията от реални пликове. Тестов пликове следователно никога не достигат вашия URL адрес за производство, а всеки товар указва "sandbox" (true или false).

Да продължим

• Разработчик на Хъб
• Електронен подпис API
• Интеграции на местните жители
• Страница за сигурност
• План и цени