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"
}
}
}
idto identyfikator zdarzenia. Ponowienia mają ten samid, więc po nim rozpoznasz duplikat.typeto jedno ze zdarzeń z tabeli wyżej.api_versionto wersja tej struktury. Zmianę, przez którą Twój kod mógłby przestać działać, wprowadzimy pod nową wersją.data.documentto dokument: naszid, 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.filingto wysyłka do KSeF:status, środowisko (ksef_environment:test,demoalboproduction), numer KSeF i link weryfikacyjny KOD I (ksef_verification_url). Do tego:rejectionz polamicodeimessage, gdy KSeF odrzucił dokument,held_reason, gdy dokument wstrzymaliśmy, na przykładout_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_unusablealbofiling_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-Eventz typem zdarzenia, takim samym jaktype,KSeF-Kit-Deliveryz identyfikatorem wysyłki, takim samym przy każdym ponowieniu,KSeF-Kit-Signaturez 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:
- Weź surową treść żądania, zanim ją sparsujesz. JSON zapisany na nowo ma inne bajty i podpis się nie zgodzi.
- Policz HMAC-SHA256 z
t, kropki i tej treści. Kluczem jest Twój sekret. - Porównaj wynik z każdym
v1z nagłówka funkcją, która porównuje w stałym czasie (w przykładach niżej toOpenSSL.secure_compareicrypto.timingSafeEqual). Wystarczy, że zgodzi się jeden. - Odrzuć żądanie, gdy
tróż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
localhosti127.0.0.1, sieci10.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::/10i 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.