Webhooks
A webhook is a message we send to your app when KSeF accepts or rejects an invoice or a correction, or when we hold or block one. Your system doesn't have to keep asking us how a document is doing. It hears on its own, signed.
You add an endpoint, the URL we send events to, in the app under Webhooks. An account can have up to 5 endpoints. Each one receives every event on the account.
Events
| Event | When we send it |
|---|---|
invoice.accepted |
KSeF accepted the invoice and gave it a KSeF number. |
invoice.rejected |
KSeF rejected the invoice. You get the rejection code and message. |
invoice.held |
We held the invoice and didn't send it to KSeF, for example because the sale is outside KSeF. You get the reason. |
invoice.blocked |
We couldn't send the invoice, for example because of the plan's limit or no KSeF connection. You get the reason. |
correction.accepted, correction.rejected, correction.held, correction.blocked |
The same for a correction (KOR) made from a Stripe credit note. |
ping |
The test event from the Send a test event button. |
Every new attempt to file a document is a new event. The same invoice can arrive as invoice.blocked first and, once the limit has room, as invoice.accepted.
The payload
Every event is JSON in a POST request:
{
"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"
}
}
}
ididentifies the event. Retries carry the sameid, so use it to spot a duplicate.typeis one of the events in the table above.api_versionnames this shape. A change that could break your code ships under a new version.data.documentis the document: ourid, its number, the Stripe invoice id (stripe_invoice_id) or credit note id (stripe_credit_note_id) and the issue date. A correction also hasinvoice, the invoice it corrects.data.filingis the filing to KSeF:status, the environment (ksef_environment:test,demoorproduction), the KSeF number and the KOD I verification link (ksef_verification_url). Plus:rejectionwithcodeandmessagewhen KSeF rejected the document,held_reasonwhen we held it, for exampleout_of_ksef_scope(what each reason means is in Rejections & troubleshooting),blocked_reasonwhen we blocked it:free_tier_exhausted(the plan's limit),company_profile_incomplete,ksef_not_connected,ksef_credential_unusableorfiling_interrupted.
A field that doesn't apply to the event is null. We send no buyer details, no amounts and no invoice content, and never a token, key or secret. Fetch the invoice's details from Stripe by its id.
A ping event carries only webhook_endpoint.id in data.
Every request also has these headers:
KSeF-Kit-Eventwith the event type, the same astype,KSeF-Kit-Deliverywith the delivery id, the same on every retry,KSeF-Kit-Signaturewith the signature.
Answer with a 2xx straight away and do the rest of the work in the background. We don't read or store what you reply.
Checking the signature
When you add an endpoint you get its signing secret, which starts with kkwhsec_. We show it only once, so store it in your app's configuration right away. We sign every request with it in this header:
KSeF-Kit-Signature: t=1763203327,v1=5f0c2a8e91b4d7c3a6e5f8b2d1c4a7e9f3b6d8c2a5e7f1b4d9c3a6e8f2b5d7c1
t is when we sent it, in seconds since 1 January 1970. v1 is the HMAC-SHA256 of t, a dot and the raw request body, keyed with your secret. To check it:
- Take the raw request body before you parse it. Re-serialised JSON has different bytes and won't match.
- Compute the HMAC-SHA256 of
t, a dot and that body, keyed with your secret. - Compare the result with every
v1in the header using a constant-time comparison. One match is enough. - Refuse the request when
tis more than 5 minutes from your clock. That stops anyone replaying an old request.
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
In Rails the raw body is request.raw_post and the header is 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);
});
}
In Express, express.raw({ type: "application/json" }) gives you the raw body, and req.get("KSeF-Kit-Signature") the header.
You can generate a new secret on the endpoint's page. For the next 24 hours we sign with both the old and the new secret, so the header carries two v1 fields. You have a day to deploy the new secret without losing a delivery. You can't generate another one until that day is over, so the secret you are running never stops working early.
Retries and switching off
A delivery succeeds when your server answers with a 2xx. We wait at most 10 seconds for the answer. We don't follow redirects, so a 3xx counts as a failure too.
After a failure we try again, waiting longer each time: 5 seconds, 25 seconds, 2 minutes, 10 minutes, 52 minutes, 4 hours and 22 hours. That's 8 attempts over about 27 hours. The test event is sent only once.
When an endpoint fails 10 deliveries in a row and has been failing for more than a day, we switch it off and email the account owner. Filing to KSeF carries on. Only the webhooks stop. Events from while the endpoint was off aren't sent later. Once it's fixed, switch it back on in the settings.
The endpoint's page keeps a delivery log for the last 30 days: the response code, the time taken, the attempts and the kind of error.
Where we send from
We send webhooks from these IP addresses:
46.224.192.230
If your server only accepts traffic from listed addresses, add them to the allowlist. The list may change one day, and the current one is always here and in the webhook settings. That's why the list is only an extra: always check the signature too.
Which URLs we accept
We send requests from our server to the address you give us. So nobody can use that to look inside our network, we only accept addresses reachable on the public internet:
https://only, on the standard port 443 only,- no username or password in the URL,
- the host may not lead to a local, private or reserved address. We refuse
localhostand127.0.0.1, the networks10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.64.0.0/10,169.254.0.0/16(the cloud server metadata address included),0.0.0.0/8, multicast and reserved addresses, and in IPv6::1,fc00::/7,fe80::/10and IPv4 addresses written as IPv6.
We check the address when you save it and again before every delivery. We turn the host name into an IP address once and connect to exactly that address, so a DNS answer changed in between makes no difference. If even one of the host's addresses is private, we send nothing.
That's why http://localhost:3000 won't work, not even for testing. To test locally, put your local server behind a public HTTPS address, for example with Cloudflare Tunnel or ngrok. If you run KSeF Kit on your own server, you can set WEBHOOKS_ALLOW_LOCALHOST=1 in development mode. We then also accept http://localhost, 127.0.0.1 and [::1] on any port. Outside development mode the setting does nothing.