Webhooks - przegląd

Jak odbierać powiadomienia z KSeFCore w czasie rzeczywistym przez webhooki

Webhooki pozwalają Twojej aplikacji odbierać powiadomienia o zdarzeniach w KSeFCore w czasie rzeczywistym. Zamiast regularnie odpytywać API o status, możesz po prostu nasłuchiwać na webhooki.

Jak działają webhooki

1. Konfiguracja - Rejestrujesz endpoint URL w panelu KSeFCore
2. Zdarzenie - W systemie zachodzi ważne zdarzenie (np. faktura wysłana)
3. Wysyłka - KSeFCore wysyła POST request na Twój endpoint
4. Odbiór - Twoja aplikacja przetwarza powiadomienie

Konfiguracja webhooka

1. Przygotuj endpoint

Twój endpoint musi:

• Akceptować requesty POST
• Odpowiadać statusami 2xx dla sukcesu
• Weryfikować podpis HMAC (patrz bezpieczeństwo)
• Obsługiwać retry strategy

// Przykład endpointu w Express.js
app.post('/webhooks/ksefcore', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-webhook-signature'];
const timestamp = req.headers['x-webhook-timestamp'];
const eventType = req.headers['x-event-type'];
const eventId = req.headers['x-event-id'];

// Weryfikacja podpisu
if (!verifySignature(req.body, signature, timestamp)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

// Przetwarzanie zdarzenia
const payload = JSON.parse(req.body.toString('utf8'));
const { type, data } = payload;

switch (type) {
  case 'ksef.outgoing.sent':
    handleOutgoingSent(data);
    break;
  case 'ksef.outgoing.accepted':
    handleOutgoingAccepted(data);
    break;
  // ... inne zdarzenia
}

// Potwierdzenie odbioru
res.status(204).end();
});

2. Zarejestruj webhook

Zaloguj się do panelu KSeFCore i przejdź do:

1. Ustawienia → Webhooki
2. Dodaj nowy webhook
3. Wprowadź URL endpointu
4. Wybierz zdarzenia do obserwowania
5. Skonfiguruj ustawienia bezpieczeństwa

Struktura payloadu webhooka

Każdy webhook ma standardową strukturę:

{
"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
}
}

Pola payloadu

• id - Unikalny ID zdarzenia (event_id) — użyj do idempotencji
• type - Typ zdarzenia (event type)
• version - Wersja envelope (zawsze 1)
• created_at - Czas utworzenia zdarzenia (ISO 8601)
• org_id - ID organizacji (jeśli znane)
• client_id - ID klienta
• resource - Kontekst biznesowy (np. submission/document)
• correlation_id - Id do korelacji w logach i idempotencji
• data - Dane specyficzne dla zdarzenia

Typy zdarzeń

Faktury sprzedażowe

• ksef.outgoing.queued - Zgłoszenie przyjęte i zakolejkowane
• ksef.outgoing.sent - Request zarejestrowany w KSeF (mamy session_reference i invoice_reference); finalny wynik dopiero w accepted/rejected
• ksef.outgoing.accepted - UPO dostępne, zgłoszenie zaakceptowane
• ksef.outgoing.rejected - Odrzucenie przez KSeF
• ksef.outgoing.failed - Finalna porażka po stronie KSeFCore

Faktury kosztowe (sync)

• ksef.incoming.synced - Dokumenty zapisane w bazie
• ksef.incoming.failed - Błąd synchronizacji

Retry strategy

KSeFCore ponawia wysyłkę tylko dla błędów uznanych za retryable:

• 408, 429, 5xx
• timeouty i błędy sieciowe

Inne 4xx są traktowane jako błąd finalny.

| Próba | Opóźnienie | |-------|------------| | 1 | natychmiast | | 2 | 60 sekund | | 3 | 300 sekund | | 4 | 900 sekund | | 5 | 3600 sekund | | 6 | 7200 sekund |

Po przekroczeniu limitu prób webhook jest oznaczany jako failed i możesz zobaczyć błąd w panelu.

Idempotentność webhooków

Każde zdarzenie ma unikalne ID (id). Użyj go do zapobiegania duplikatom:

// Sprawdź czy zdarzenie już przetworzono
const processedEventId = await db.get('processed_events', webhook.id);
if (processedEventId) {
return res.status(200).json({ received: true, duplicate: true });
}

// Przetwarzanie...
await processWebhook(webhook);

// Zapisz ID przetworzonego zdarzenia
await db.set('processed_events', webhook.id, true);
console.log('Processed webhook: ' + webhook.id);

Testowanie webhooków

Tryb testowy

W panelu możesz włączyć tryb testowy dla webhooka:

• Wysyłane są tylko testowe zdarzenia
• Możesz zobaczyć pełne requesty i odpowiedzi
• Łatwiejsze debugowanie bez wpływu na produkcję

Narzędzia do testowania

Użyj narzędzi jak ngrok lub localtunnel do testowania lokalnego endpointu:

# Uruchom ngrok
ngrok http 3000

# Otrzymasz publiczny URL
# https://abc123.ngrok.io -> http://localhost:3000

# Użyj tego URL w konfiguracji webhooka

Best practices

1. Szybkie odpowiedzi

• Odpowiadaj jak najszybciej (poniżej 5 sekund)
• Przetwarzanie w tle dla ciężkich operacji
• Zwróć 200 OK przed zakończeniem przetwarzania

2. Obsługa błędów

• Loguj wszystkie requesty webhooków
• Monitoruj błędy i retry attempts
• Implementuj alerting dla critical failures

3. Bezpieczeństwo

• Zawsze weryfikuj podpis HMAC
• Używaj HTTPS
• Ogranicz dostęp do endpointu (IP whitelist jeśli możliwe)

4. Monitorowanie

• Śledź metryki webhooków (success rate, latency)
• Monitoruj kolejki przetwarzania
• Alerty dla webhook failures