Веб-буки отримуйте підпис події в реальному часі

Формат корисної навантаження

Усі доставки мають однакову схему 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, який залишається джерелом істини. Також зверніть увагу на ручне відтворення з черги недоставлених повідомлень більш ніж за 7 днів після події: посилання в корисному навантаженню має закінчитися, кінцева точка API — ні.

Підпис HMAC обчислюється на грубому тілі, як відправлено не змінюйте пробіли, перепараси JSON часто змінюють порядок ключів і порушують перевірку.

Перевірка підпису HMAC

Кожен запит підписується вашим webhook-секретом (показаний лише один раз під час створення підписки). Підпис передається в заголовку `X-Certyneo-Signature` : це HMAC-SHA256 від сирого тіла запиту, закодований у шістнадцятковому форматі, без префіксу чи часової мітки. ЗАВЖДИ перевіряйте підпис перед обробкою корисного навантаження — без цього кроку будь-хто може підробити подію та викликати вашу 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 — її можна переглянути та повторити з вашої панелі керування, але автоматичних повторів не буде. Явна відмова (401, 403, 404, 410, 422…) ніколи не повторюється: відповідь не зміниться, подія одразу потрапляє в чергу dead-letter.

Вказані затримки є мінімальними: перевірка повторів здійснюється за розкладом cron, тому спроба може піти трохи пізніше за теоретичну час. Закинуті події перелічені в Webhooks → Помилки з кнопкою ручного повтору і без обмеження терміну зберігання. Endpoint, який зазнав п'ять остаточних помилок — або який повертає 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
• Корінні інтеграції
• Страница безпеки
• Планування та тарифи