KSeF Kit

Webhooki

Webhook to wiadomość, którą wysyłamy do Twojej aplikacji, gdy KSeF przyjmie albo odrzuci fakturę lub korektę, albo gdy ją wstrzymamy lub zablokujemy. Twój system nie musi co chwilę pytać o stan dokumentu. Dostaje go sam, z podpisem.

Punkt końcowy, czyli adres URL, na który wysyłamy zdarzenia, dodajesz w aplikacji w zakładce Webhooki. Konto może mieć do 5 punktów końcowych. Każdy dostaje wszystkie zdarzenia konta.

Zdarzenia

Zdarzenie Kiedy je wysyłamy
invoice.accepted KSeF przyjął fakturę i nadał jej numer KSeF.
invoice.rejected KSeF odrzucił fakturę. Dostajesz kod i komunikat odrzucenia.
invoice.held Wstrzymaliśmy fakturę i nie wysłaliśmy jej do KSeF, na przykład dlatego, że sprzedaż nie podlega KSeF. Dostajesz powód.
invoice.blocked Nie mogliśmy wysłać faktury, na przykład przez limit planu albo brak połączenia z KSeF. Dostajesz powód.
correction.accepted, correction.rejected, correction.held, correction.blocked To samo dla korekty (KOR) z noty kredytowej w Stripe.
ping Zdarzenie testowe z przycisku Wyślij zdarzenie testowe.

Gdy wysyłamy dokument ponownie, dostajesz nowe zdarzenie. Ta sama faktura może więc przyjść najpierw jako invoice.blocked, a po zwolnieniu miejsca w limicie jako invoice.accepted.

Treść zdarzenia

Każde zdarzenie wysyłamy jako JSON w żądaniu POST:

{
  "id": "evt_6vGq2RkT9mWbXc4YhN8pLsJd",
  "object": "event",
  "type": "invoice.accepted",
  "api_version": "2026-11-15",
  "account": "acct_KpW3nV8xQz2Ld7Rm5Ty9Bc4H",
  "created": "2026-11-15T10:42:07Z",
  "data": {
    "document": {
      "object": "invoice",
      "id": "inv_Z8yXc2Vb7Nm4Qw9Er3Ty6Ui1",
      "number": "FV/2026/11/014",
      "stripe_invoice_id": "in_1QdT5x2eZvKYlo2C8b4n7mPq",
      "issued_at": "2026-11-14T16:03:51Z"
    },
    "filing": {
      "id": "sub_Hj4Kl8Zx2Cv6Bn9Mq3Wr7Ts5",
      "status": "accepted",
      "ksef_environment": "production",
      "ksef_number": "1111111111-20261115-0A1B2C3D4E5F-12",
      "ksef_verification_url": "https://qr.ksef.mf.gov.pl/invoice/1111111111/14-11-2026/Ufk3h5Dz2xKqP9vTnL0wYbR7sA4cJ8mE1gH6iN2oQ5U",
      "rejection": null,
      "held_reason": null,
      "blocked_reason": null,
      "created_at": "2026-11-15T10:41:58Z",
      "settled_at": "2026-11-15T10:42:06Z"
    }
  }
}
  • id to identyfikator zdarzenia. Ponowienia mają ten sam id, więc po nim rozpoznasz duplikat.
  • type to jedno ze zdarzeń z tabeli wyżej.
  • api_version to wersja tej struktury. Zmianę, przez którą Twój kod mógłby przestać działać, wprowadzimy pod nową wersją.
  • data.document to dokument: nasz id, numer, identyfikator faktury w Stripe (stripe_invoice_id) albo noty kredytowej (stripe_credit_note_id) i data wystawienia. Korekta ma też invoice, czyli fakturę, którą koryguje.
  • data.filing to wysyłka do KSeF: status, środowisko (ksef_environment: test, demo albo production), numer KSeF i link weryfikacyjny KOD I (ksef_verification_url). Do tego:
    • rejection z polami code i message, gdy KSeF odrzucił dokument,
    • held_reason, gdy dokument wstrzymaliśmy, na przykład out_of_ksef_scope (co znaczy każdy powód, piszemy w Odrzucenia i problemy),
    • blocked_reason, gdy dokument zablokowaliśmy: free_tier_exhausted (limit planu), company_profile_incomplete, ksef_not_connected, ksef_credential_unusable albo filing_interrupted.

Pole, które nie dotyczy danego zdarzenia, ma wartość null. Nie wysyłamy danych nabywcy, kwot ani treści faktury. Nie wysyłamy też tokenów, kluczy ani sekretów. Szczegóły faktury pobierzesz ze Stripe po jej identyfikatorze.

Zdarzenie ping ma w data tylko webhook_endpoint.id.

Każde żądanie ma też nagłówki:

  • KSeF-Kit-Event z typem zdarzenia, takim samym jak type,
  • KSeF-Kit-Delivery z identyfikatorem wysyłki, takim samym przy każdym ponowieniu,
  • KSeF-Kit-Signature z podpisem.

Odpowiedz kodem 2xx od razu, a dalszą pracę zrób w tle. Liczy się tylko kod odpowiedzi, jej treści nie zapisujemy.

Sprawdzanie podpisu

Po dodaniu punktu końcowego dostajesz sekret podpisu. Zaczyna się od kkwhsec_. Pokazujemy go tylko raz, więc od razu zapisz go w konfiguracji swojej aplikacji. Każde żądanie podpisujemy nim w nagłówku:

KSeF-Kit-Signature: t=1763203327,v1=5f0c2a8e91b4d7c3a6e5f8b2d1c4a7e9f3b6d8c2a5e7f1b4d9c3a6e8f2b5d7c1

t to czas wysyłki w sekundach od 1 stycznia 1970 roku. v1 to HMAC-SHA256 z tekstu złożonego z t, kropki i surowej treści żądania, liczony Twoim sekretem. Żeby sprawdzić podpis:

  1. Weź surową treść żądania, zanim ją sparsujesz. JSON zapisany na nowo ma inne bajty i podpis się nie zgodzi.
  2. Policz HMAC-SHA256 z t, kropki i tej treści. Kluczem jest Twój sekret.
  3. Porównaj wynik z każdym v1 z nagłówka funkcją, która porównuje w stałym czasie (w przykładach niżej to OpenSSL.secure_compare i crypto.timingSafeEqual). Wystarczy, że zgodzi się jeden.
  4. Odrzuć żądanie, gdy t różni się od Twojego zegara o więcej niż 5 minut. Tak nikt nie powtórzy starego żądania.

Ruby:

require "openssl"

def ksef_kit_signature_valid?(raw_body, header, secret, tolerance: 300)
  pairs = header.to_s.split(",").map { |part| part.strip.split("=", 2) }
  timestamp = Integer(pairs.assoc("t")&.last, exception: false)
  return false unless timestamp && (Time.now.to_i - timestamp).abs <= tolerance

  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
  pairs.any? { |key, digest| key == "v1" && digest && OpenSSL.secure_compare(digest, expected) }
end

W Rails surowa treść to request.raw_post, a nagłówek to request.headers["KSeF-Kit-Signature"].

Node.js:

const crypto = require("node:crypto");

function ksefKitSignatureValid(rawBody, header, secret, tolerance = 300) {
  const pairs = String(header || "").split(",").map((part) => part.trim().split("="));
  const timestamp = Number(pairs.find(([key]) => key === "t")?.[1]);
  if (!Number.isInteger(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > tolerance) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  return pairs.some(([key, digest]) => {
    if (key !== "v1" || !digest) return false;
    const candidate = Buffer.from(digest, "hex");
    return candidate.length === expected.length && crypto.timingSafeEqual(candidate, expected);
  });
}

W Expressie surową treść dostaniesz przez express.raw({ type: "application/json" }), a nagłówek przez req.get("KSeF-Kit-Signature").

Nowy sekret wygenerujesz na stronie punktu końcowego. Przez 24 godziny podpisujemy wtedy wysyłki starym i nowym sekretem, więc nagłówek ma dwa pola v1. Masz dobę na wdrożenie nowego sekretu i nie tracisz żadnej wysyłki. Kolejny nowy sekret wygenerujesz dopiero po tej dobie, żeby sekret, który masz u siebie, nigdy nie przestał działać przed czasem.

Ponowienia i wyłączenie

Wysyłka jest udana, gdy Twój serwer odpowie kodem 2xx. Na odpowiedź czekamy najwyżej 10 sekund. Nie przechodzimy pod adres z przekierowania, więc kod 3xx też jest błędem.

Po błędzie próbujemy ponownie i za każdym razem czekamy dłużej: 5 sekund, 25 sekund, 2 minuty, 10 minut, 52 minuty, 4 godziny i 22 godziny. To razem 8 prób w ciągu około 27 godzin. Zdarzenie testowe wysyłamy tylko raz.

Gdy punkt końcowy nie przyjmie 10 wysyłek z rzędu, a błędy trwają już ponad dobę, wyłączamy go i piszemy do właściciela konta. Faktury dalej składamy w KSeF. Wyłączenie dotyczy tylko webhooków. Zdarzeń z czasu, gdy punkt końcowy był wyłączony, nie wysyłamy później. Po naprawie włącz go w ustawieniach.

Na stronie punktu końcowego jest dziennik wysyłek z ostatnich 30 dni: kod odpowiedzi, czas, liczba prób i rodzaj błędu.

Adresy, z których wysyłamy

Webhooki wysyłamy z tych adresów IP:

  • 46.224.192.230

Jeśli Twój serwer przyjmuje ruch tylko z wybranych adresów, dopisz je do listy dozwolonych. Lista może się kiedyś zmienić. Aktualna jest zawsze tutaj i w ustawieniach webhooków. Lista adresów nie zastąpi podpisu, więc sprawdzaj go zawsze.

Jakie adresy URL przyjmujemy

Wysyłamy żądania z naszego serwera pod adres, który podasz. Żeby nikt nie mógł w ten sposób zajrzeć do naszej sieci, przyjmujemy tylko adresy dostępne publicznie w internecie:

  • tylko https:// i tylko zwykły port 443,
  • bez loginu i hasła w adresie,
  • host nie może prowadzić do adresu lokalnego, prywatnego ani zarezerwowanego. Odrzucamy localhost i 127.0.0.1, sieci 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 169.254.0.0/16 (w tym adres metadanych serwera w chmurze), 0.0.0.0/8, adresy multicast i zarezerwowane, a w IPv6 ::1, fc00::/7, fe80::/10 i adresy IPv4 zapisane jako IPv6.

Adres sprawdzamy przy zapisie i jeszcze raz przed każdą wysyłką. Nazwę hosta zamieniamy na adres IP raz i łączymy się właśnie z nim. Jeśli DNS w międzyczasie zacznie wskazywać inny adres, nie ma to znaczenia. Gdy choć jeden adres hosta jest prywatny, nie wysyłamy nic.

Dlatego http://localhost:3000 nie zadziała, także do testów. Żeby testować u siebie, wystaw lokalny serwer pod publicznym adresem HTTPS, na przykład przez Cloudflare Tunnel albo ngrok. Jeśli uruchamiasz KSeF Kit na własnym serwerze, w trybie deweloperskim możesz ustawić WEBHOOKS_ALLOW_LOCALHOST=1. Wtedy przyjmujemy też http://localhost, 127.0.0.1 i [::1] na dowolnym porcie. Poza trybem deweloperskim to ustawienie nic nie robi.