Webhooki obiegu dokumentów

Webhooki pozwalają odbierać informacje o uruchomieniu procesu, aktywności odbiorców, potwierdzeniu dokumentu i pieczętowaniu bez cyklicznego odpytywania API obiegu dokumentów.

Spis treści

• Konfiguracja
• Nagłówki i podpis
• Przykładowy payload
• Typy zdarzeń
• Anulowanie, odrzucenie i wygaśnięcie
• Powtórzenia i ponowienia
• Dobre praktyki

Konfiguracja

Webhooki konfiguruje administrator konta w ustawieniach modułu "Obieg dokumentów" w panelu SARE.

1. Wskaż publicznie dostępny adres HTTPS odbierający żądania POST.
2. Wybierz typy zdarzeń, które chcesz otrzymywać.
3. Zapisz ustawienia i wykonaj test webhooka.
4. Użyj sekretu z ustawień modułu do weryfikacji podpisu po stronie odbiorczej.

Konfiguracja obowiązuje dla konta. Adresu webhooka, sekretu ani listy zdarzeń nie przekazuje się przy tworzeniu procesu przez API. Bez adresu URL lub bez wybranego typu zdarzenia wysyłka nie jest kolejkowana.

Test wysyła zdarzenie webhook.test. Ma ono pola event, eventId, occurredAt, source: "aurora.doc-flow", account i details. Obiekt account zawiera tenantId i integrationKey, a details.message opisuje test. Test nie zawiera obiektu process i wykonuje jedną próbę dostarczenia.

Nagłówki i podpis

Nagłówek	Znaczenie
Content-Type	application/json
X-Confirmation-Event	Typ zdarzenia, zgodny z event w payloadzie
X-Confirmation-Id	Identyfikator zdarzenia, zgodny z eventId w payloadzie
X-Confirmation-Signature	Podpis w formacie sha256=<hex HMAC-SHA256>, dołączany, gdy dostępny jest sekret

Podpis obejmuje dokładną treść JSON wysłaną w żądaniu. Do weryfikacji użyj surowych bajtów body, zanim parser JSON zmieni je w obiekt. Ponowna serializacja może zmienić kolejność pól lub formatowanie i unieważnić podpis.

Przykład w Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto'

function verifyWebhook(rawBody, signature, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof signature !== 'string') {
    return false
  }

  const match = /^sha256=([a-f0-9]{64})$/.exec(signature)
  if (!match) {
    return false
  }

  const expected = createHmac('sha256', secret).update(rawBody).digest()
  const received = Buffer.from(match[1], 'hex')

  return received.length === expected.length && timingSafeEqual(received, expected)
}

const signature = request.headers['x-confirmation-signature']
if (!verifyWebhook(rawBody, signature, webhookSecret)) {
  throw new Error('Invalid webhook signature')
}

const payload = JSON.parse(rawBody.toString('utf8'))

rawBody w przykładzie to Buffer z oryginalną treścią żądania, a webhookSecret to sekret z ustawień modułu. Skonfiguruj swój serwer tak, aby zachował surowe body przed parsowaniem JSON.

Przykładowy payload

Zdarzenie step.confirmed:

{
  "event": "step.confirmed",
  "eventId": "dfw_t1_k8V4wN7xP2mQ6rS9aB3c",
  "occurredAt": "2026-10-19T10:15:00.000Z",
  "process": {
    "id": "dfp_t1_n7K2vP4qR8sT6wX9aB3c",
    "referenceId": "REF-2026-0001",
    "externalId": "case-2026-0001",
    "documentId": "dfd_t1_m3N8pQ2rS6tV4wX9aB7c",
    "sender": {
      "name": "Biuro obsługi",
      "email": "[email protected]",
      "replyTo": "[email protected]"
    }
  },
  "details": {
    "stepKey": "step_1",
    "actor": "recipient",
    "confirmedAt": "2026-10-19T10:15:00.000Z",
    "ip": "192.0.2.10",
    "userAgent": "Mozilla/5.0",
    "latestArtifactVersion": 2,
    "latestArtifactKind": "artifact",
    "fileAccessMode": "pin",
    "approvalMode": "button_only",
    "processStatus": "in_progress",
    "recipientEmail": "[email protected]"
  }
}

Pole	Znaczenie
event	Typ zdarzenia
eventId	Identyfikator zdarzenia, używany także przy ponowieniach
occurredAt	Czas utworzenia zdarzenia webhooka w formacie ISO 8601
process.id	Identyfikator procesu używany w API
process.referenceId	Numer referencyjny procesu
process.externalId	Identyfikator w systemie integratora lub null
process.documentId	Identyfikator dokumentu procesu
process.sender	Nadawca wiadomości: name, email, replyTo; dla starszego procesu może mieć wartość null
details	Szczegóły zależne od typu zdarzenia

Jeśli zdarzenie wskazuje krok przez stepKey, details.recipientEmail zawiera e-mail tego odbiorcy, o ile jest dostępny. Pola ip i userAgent mogą mieć wartość null. Dane podpisu odręcznego signatureDataUrl nie są wysyłane w webhookach.

Dla step.confirmed sposób dostępu i zatwierdzenia opisują fileAccessMode oraz approvalMode. Payload nie zawiera pól confirmationMethod ani sourceIp znanych ze starszej dokumentacji.

Dla procesu należącego do wysyłki masowej w details.campaign pojawia się dodatkowy kontekst: id, name, recipientId, executionId, documentUploadId, emailSubject, emailPreheader, scheduledAt, startedAt, expiresAt, fileAccessMode, approvalMode, pinDeliveryChannel, pinFallbackToEmail, includeSignatureCard, sealingEnabled i eurocertSealId. Część tych wartości może być null.

Typy zdarzeń

Poniższe typy są dostępne do wyboru w ustawieniach modułu:

Typ zdarzenia	Znaczenie
process.created	Utworzenie procesu; uwaga dotycząca emisji poniżej
process.started	Uruchomienie procesu z odbiorcami
email.sent	Przekazanie wiadomości e-mail do kolejki wysyłkowej, np. linku dostępu lub PIN-u
sms.sent	Przekazanie wiadomości SMS do wysyłki
sms.delivered	Zdarzenie emitowane po udanym wywołaniu wysyłki SMS; uwaga dotycząca doręczenia poniżej
step.email_sent	Zakolejkowanie wiadomości z linkiem dostępu dla kroku
step.opened	Otwarcie kroku przez link odbiorcy
step.viewed	Zarejestrowanie wyświetlenia dokumentu
step.confirmed	Zatwierdzenie kroku zgodnie z jego trybem
step.signed	Złożenie podpisu odręcznego w kroku
process.cancelled	Wycofanie procesu, odrzucenie przez odbiorcę lub upływ terminu procesu
artifact.sealing_started	Rozpoczęcie pieczętowania dokumentu końcowego
artifact.sealed	Utworzenie opieczętowanej wersji dokumentu
artifact.sealing_failed	Nieudane pieczętowanie dokumentu
process.completed	Zakończenie wszystkich kroków procesu

Uwaga

process.created jest dostępne w ustawieniach, ale obecna ścieżka tworzenia procesu zapisuje je tylko w historii procesu. Do powiadomienia o rozpoczęciu obiegu wybierz process.started. Zapis szkicu bez odbiorców nie uruchamia tego zdarzenia.

email.sent i step.email_sent nie potwierdzają dotarcia wiadomości do skrzynki odbiorcy. Mogą opisywać to samo zakolejkowanie pod różnymi nazwami, z osobnymi eventId. sms.delivered jest obecnie emitowane bezpośrednio po udanej operacji wysyłki SMS i nie stanowi niezależnego raportu doręczenia na telefon.

process.completed nie gwarantuje udanego pieczętowania. W details tego zdarzenia znajdują się completedAt, latestArtifactVersion, latestArtifactKind, latestSealedVersion, latestSealedKind i processStatus. Gdy opieczętowana wersja nie powstała, latestSealedVersion i latestSealedKind mają wartość null. Wynik pieczętowania rozpoznawaj także po artifact.sealed lub artifact.sealing_failed.

W historii procesu występują również typy process.paused, process.resumed, email.accepted, email.failed, step.pin_verified, password.requested i password.delivered. Nie są dostępne do wyboru w konfiguracji webhooków. Nie należy oczekiwać ich jako powiadomień webhook.

Anulowanie, odrzucenie i wygaśnięcie

Każdy z tych scenariuszy używa zdarzenia process.cancelled. Rozróżniaj je na podstawie details:

Scenariusz	Charakterystyczne pola details
Wycofanie przez operatora	processStatus: "cancelled" i reason, które może być null
Odrzucenie przez odbiorcę	actor: "recipient", stepKey, stepStatus: "failed", rejectedAt, reason, ip, userAgent i e-mail odbiorcy
Upływ terminu expiresAt	reason: "expired", completedAt i readUntil

Przykładowe details dla odrzucenia dokumentu:

{
  "processStatus": "cancelled",
  "stepKey": "step_1",
  "stepStatus": "failed",
  "actor": "recipient",
  "rejectedAt": "2026-10-19T10:20:00.000Z",
  "reason": "Proszę poprawić dane w dokumencie.",
  "ip": "192.0.2.10",
  "userAgent": "Mozilla/5.0",
  "recipientEmail": "[email protected]"
}

Powtórzenia i ponowienia

Webhook jest wysyłany jako POST z limitem czasu odpowiedzi wynoszącym 30 sekund. Odbiorca powinien zwrócić kod 2xx po trwałym zapisaniu zdarzenia.

• Standardowa wysyłka wykonuje maksymalnie 3 próby łącznie: pierwszą próbę i 2 ponowienia.
• Ponowienia są planowane po 30 sekundach, a następnie po 60 sekundach od nieudanej próby. Obciążenie kolejki może wydłużyć oczekiwanie.
• Ponawiane są błędy połączenia, przekroczenie limitu czasu oraz odpowiedzi błędów HTTP, także 4xx.
• Ponowienie zachowuje eventId, treść żądania, adres docelowy i nagłówki zapisane przy utworzeniu wysyłki.
• Administrator może sprawdzić historię dostarczeń i ręcznie ponowić wysyłkę w panelu SARE.
• Historia dostarczenia webhooka ma retencję 30 dni od utworzenia wpisu. Ponowienie nie przedłuża tego terminu.

To samo zdarzenie może zostać dostarczone więcej niż raz. Zapisuj obsłużone eventId i odpowiadaj kodem 2xx również na poprawnie podpisane duplikaty, bez ponownego wykonywania operacji biznesowej. Nie opieraj działania integracji na kolejności dostarczenia webhooków.

Dobre praktyki

• Weryfikuj podpis na surowym body i dopiero potem przetwarzaj dane biznesowe.
• Zapisuj eventId, event oraz process.id, aby móc powiązać zdarzenie z procesem i wykryć duplikat.
• Po trwałym zapisaniu webhooka przetwarzaj dłuższe zadania asynchronicznie.
• Obsługuj brak opcjonalnych pól, wartości null oraz nowe pola dodane do payloadu.
• Pobieraj aktualny stan procesu i właściwą wersję PDF przez API obiegu dokumentów.