Webhooki

Autosignly wysyła POST z ciałem JSON na adres webhooka skonfigurowany przy kluczu API, gdy wydarzy się zdarzenie asynchroniczne. Nazwy zdarzeń subskrybujesz w aplikacji Autosignly (API → Webhooki).

To nie są endpointy tego API — wystawiasz odbiornik, Autosignly go woła. Ten sam katalog (typy zdarzeń, schematy treści, nagłówki podpisu) jest w dokumencie OpenAPI w sekcji Webhooks.

Weryfikacja dostawy

Każda dostawa jest podpisana. Sprawdź nagłówki wobec surowego ciała żądania zanim sparsujesz JSON — ponowna serializacja zmienia bajty i podpis się nie zgodzi. SDK udostępnia to jako webhooks.verify (Python, Node.js) albo Webhooks.verify (Java) — oraz nierzucający wyjątkiem odpowiednik is_valid/isValid.

1. Odczytaj X-Webhook-Timestamp (sekundy Unix) i X-Webhook-Signature.
2. Policz hex(HMAC-SHA256(webhook_key, timestamp + "." + raw_body)).
3. Zaakceptuj, gdy którykolwiek wpis X-Webhook-Signature (oddzielone przecinkami) jest równy v1=<digest> (porównanie w stałym czasie). Kilka podpisów v1= pojawia się podczas rotacji klucza.
4. Odrzuć, gdy |now - timestamp| > 300 sekund (pięć minut), nawet przy poprawnym podpisie — to okno przeciw powtórzeniu dostawy.

Odpowiedz dowolnym kodem HTTP 2xx, żeby potwierdzić odbiór. Inne statusy są ponawiane.

from autosignly import webhooks

webhooks.verify(
    request.body,
    request.headers["X-Webhook-Signature"],
    webhook_key,
    request.headers["X-Webhook-Timestamp"],
)

Koperta

Ciało HTTP zawsze ma postać:

{
  "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "companyId": "7f3c1a2b-beef-4d5e-a6f7-123456789abc",
  "eventType": "DOCUMENT_SIGNED",
  "payload": {
    "documentId": "03bef6df-faca-4aee-9836-80caeeaf4418",
    "signerId": "7c2a1b4e-9d3f-4a12-8e5b-1f6c0a9d8e7b",
    "email": "[email protected]"
  },
  "companyApiId": "PROD"
}

eventId jednoznacznie identyfikuje dostawę — użyj go, żeby zignorować duplikaty. companyApiId to identyfikator środowiska (PROD albo UUID sandboxa). email jest pomijane, gdy podpisujący nie ma adresu.

Typy zdarzeń

eventType	Kiedy jest wysyłane	payload
DOCUMENT_SIGNED	Osoba podpisująca dokończyła podpis. Kolejni mogą jeszcze czekać.	{ "documentId", "signerId", "email"? }
DOCUMENT_ALL_SIGNATURES_DONE	Zebrano wszystkie wymagane podpisy.	{ "documentId" }
DOCUMENT_CANCELLED	Podpisywanie zakończyło się bez pełnego zestawu podpisów.	{ "documentId", "cancellationReason", "signerId", "cancelledAt" }
DOCUMENT_RESTORED	Anulowany dokument został przywrócony i podpisywanie może iść dalej.	{ "documentId", "restoredAt" }

cancellationReason to jedno z REJECTED_BY_SIGNER, EXPIRED, CANCELLED_BY_SENDER. signerId jest nullem, gdy proces anulował nadawca. cancelledAt i restoredAt to chwile UTC (2026-09-10T11:00:00Z).