Proszę czekać, ładujemy treść.
Lista dostępnych zdarzeń webhooków KSeFCore i przykładowe payloady
KSeFCore wysyła różne typy zdarzeń w zależności od tego, co dzieje się w systemie. Poniżej znajdziesz pełną listę zdarzeń wraz z przykładowymi payloadami.
Każde zdarzenie webhook ma standardową strukturę:
json
{
"id": "<event_id>",
"type": "ksef.outgoing.sent",
"version": 1,
"created_at": "2026-01-07T12:00:00.000000+00:00",
"org_id": "<org_uuid>",
"client_id": "<client_uuid>",
"resource": { "type": "submission", "id": "<submission_public_id>" },
"correlation_id": "<string>",
"data": {
// Dane specyficzne dla zdarzenia
}
}
Wysyłane po przyjęciu zgłoszenia i zakolejkowaniu go do wysyłki.
json
{
"id": "evt_queued_01",
"type": "ksef.outgoing.queued",
"version": 1,
"created_at": "2026-01-07T12:00:00.000000+00:00",
"org_id": "00000000-0000-0000-0000-000000000001",
"client_id": "00000000-0000-0000-0000-000000000002",
"resource": { "type": "submission", "id": "sub_public_01" },
"correlation_id": "sub_public_01",
"data": {
"submission_id": "sub_public_01",
"submission_db_id": 123,
"status": "queued",
"mode": "online",
"invoice_number": "FV/2026/01/001",
"version_group_id": "vg_01",
"version_number": 1,
"is_active_version": true,
"next_attempt_at": "2026-01-07T12:00:00.000000+00:00"
}
}Wysyłane po zapisaniu session_reference i invoice_reference — request zarejestrowany w KSeF. Finalny wynik dopiero w ksef.outgoing.accepted / ksef.outgoing.rejected.
json
{
"id": "evt_sent_01",
"type": "ksef.outgoing.sent",
"version": 1,
"created_at": "2026-01-07T12:01:00.000000+00:00",
"org_id": "00000000-0000-0000-0000-000000000001",
"client_id": "00000000-0000-0000-0000-000000000002",
"resource": { "type": "submission", "id": "sub_public_01" },
"correlation_id": "sub_public_01",
"data": {
"submission_id": "sub_public_01",
"submission_db_id": 123,
"status": "sent",
"mode": "online",
"session_reference": "S-REF-123",
"invoice_reference": "I-REF-456",
"finalize_deadline_at": "2026-01-08T12:01:00.000000+00:00"
}
}Wysyłane, gdy UPO jest dostępne i zgłoszenie zostało zaakceptowane.
json
{
"id": "evt_acc_01",
"type": "ksef.outgoing.accepted",
"version": 1,
"created_at": "2026-01-07T12:05:00.000000+00:00",
"org_id": "00000000-0000-0000-0000-000000000001",
"client_id": "00000000-0000-0000-0000-000000000002",
"resource": { "type": "submission", "id": "sub_public_01" },
"correlation_id": "sub_public_01",
"data": {
"submission_id": "sub_public_01",
"mode": "online",
"status": "accepted",
"ksef_number": "KSEF-2026-0001",
"invoice_reference": "I-REF-456",
"session_reference": "S-REF-123",
"local_filename": "sub_public_01.xml"
}
}Wysyłane, gdy zgłoszenie zostało odrzucone przez KSeF.
json
{
"id": "evt_rej_01",
"type": "ksef.outgoing.rejected",
"version": 1,
"created_at": "2026-01-07T12:05:00.000000+00:00",
"org_id": "00000000-0000-0000-0000-000000000001",
"client_id": "00000000-0000-0000-0000-000000000002",
"resource": { "type": "submission", "id": "sub_public_01" },
"correlation_id": "sub_public_01",
"data": {
"submission_id": "sub_public_01",
"mode": "online",
"status": "rejected",
"error_code": "KSEF_REJECTED",
"error_message": "Invoice rejected by KSeF validation",
"local_filename": "sub_public_01.xml"
}
}Wysyłane, gdy wystąpi finalny błąd po stronie KSeFCore (np. deadline finalizacji).
json
{
"id": "evt_fail_01",
"type": "ksef.outgoing.failed",
"version": 1,
"created_at": "2026-01-07T12:10:00.000000+00:00",
"org_id": "00000000-0000-0000-0000-000000000001",
"client_id": "00000000-0000-0000-0000-000000000002",
"resource": { "type": "submission", "id": "sub_public_01" },
"correlation_id": "sub_public_01",
"data": {
"submission_id": "sub_public_01",
"mode": "online",
"status": "failed_final",
"error_code": "FINALIZE_TIMEOUT",
"error_message": "UPO not available within deadline",
"local_filename": "sub_public_01.xml"
}
}Wysyłane gdy dokumenty zostały zapisane w bazie.
json
{
"id": "evt_in_syn_01",
"type": "ksef.incoming.synced",
"version": 1,
"created_at": "2026-01-07T12:00:10.000000+00:00",
"org_id": "00000000-0000-0000-0000-000000000001",
"client_id": "00000000-0000-0000-0000-000000000002",
"resource": { "type": "sync", "id": "ksef-sync:..." },
"correlation_id": "ksef-sync:...",
"data": {
"total": 12,
"by_direction": { "PURCHASE": 12, "SALES": 0 },
"from": "2026-01-07T00:00:00+00:00",
"to": "2026-01-07T23:59:59+00:00"
}
}Wysyłane gdy synchronizacja nie powiodła się.
json
{
"id": "evt_in_fail_01",
"type": "ksef.incoming.failed",
"version": 1,
"created_at": "2026-01-07T12:00:01.000000+00:00",
"org_id": "00000000-0000-0000-0000-000000000001",
"client_id": "00000000-0000-0000-0000-000000000002",
"resource": { "type": "sync", "id": "ksef-sync:..." },
"correlation_id": "ksef-sync:...",
"data": {
"direction": "BOTH",
"stage": "auth",
"error_code": "AUTH_CHALLENGE_FAILED",
"error_message": "..."
}
}W panelu KSeFCore wybierasz typy zdarzeń (events) oraz opcjonalnie ustawiasz filters (JSON), które dodatkowo ograniczają wysyłkę.
filters wspiera wyłącznie równość (==) — brak operatorów, brak list, brak partial match.
Rekomendowane klucze v1:
client_idresource.typeresource.iddata.direction (jeśli ma sens dla danego eventu)Przykłady:
{ "resource.type": "submission" }
{ "resource.id": "sub_public_01" }
{ "data.direction": "PURCHASE" }
W panelu możesz wysłać testowe zdarzenie do swojego endpointu: