KSeF Kit

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"
    }
  }
}
  • id identifies the event. Retries carry the same id, so use it to spot a duplicate.
  • type is one of the events in the table above.
  • api_version names this shape. A change that could break your code ships under a new version.
  • data.document is the document: our id, its number, the Stripe invoice id (stripe_invoice_id) or credit note id (stripe_credit_note_id) and the issue date. A correction also has invoice, the invoice it corrects.
  • data.filing is the filing to KSeF: status, the environment (ksef_environment: test, demo or production), the KSeF number and the KOD I verification link (ksef_verification_url). Plus:
    • rejection with code and message when KSeF rejected the document,
    • held_reason when we held it, for example out_of_ksef_scope (what each reason means is in Rejections & troubleshooting),
    • blocked_reason when we blocked it: free_tier_exhausted (the plan's limit), company_profile_incomplete, ksef_not_connected, ksef_credential_unusable or filing_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-Event with the event type, the same as type,
  • KSeF-Kit-Delivery with the delivery id, the same on every retry,
  • KSeF-Kit-Signature with 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:

  1. Take the raw request body before you parse it. Re-serialised JSON has different bytes and won't match.
  2. Compute the HMAC-SHA256 of t, a dot and that body, keyed with your secret.
  3. Compare the result with every v1 in the header using a constant-time comparison. One match is enough.
  4. Refuse the request when t is 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 localhost and 127.0.0.1, the networks 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 (the cloud server metadata address included), 0.0.0.0/8, multicast and reserved addresses, and in IPv6 ::1, fc00::/7, fe80::/10 and 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.