Polityka retry

DPay Web EID gwarantuje dostarczenie webhooków używając mechanizmu ponawiania (retry). Ten przewodnik wyjaśnia jak działa retry, kiedy endpoint zostaje automatycznie wyłączony i jak zapewnić idempotentność.

Diagram dostarczenia

DPay HUB

Twój endpoint

jeśli błąd lub timeout

po wszystkich próbach

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Harmonogram ponawiania

Jeśli Twój endpoint nie zwróci kodu 2xx w czasie 10 sekund, webhook zostanie ponowiony zgodnie z poniższym harmonogramem:

Próba	Opóźnienie	Czas od pierwszej próby
1	natychmiast	0
2	10 sekund	10s
3	1 minuta	~1 min
4	5 minut	~6 min
5	30 minut	~36 min

Po 5 nieudanych próbach dostarczenie zostaje oznaczone jako nieudane (failure_count++).

Co liczy się jako sukces?

• 2xx (200, 201, 202, 204) - sukces, koniec retry
• Inne kody (3xx, 4xx, 5xx) - niepowodzenie, ponowienie według harmonogramu
• Timeout > 10s - niepowodzenie, ponowienie
• Connection refused / DNS error - niepowodzenie, ponowienie

Auto-dezaktywacja po 50 błędach

ostrzeżenie

Po 50 kolejnych nieudanych dostarczeniach endpoint zostaje automatycznie dezaktywowany - pole disabled_at zostaje ustawione na bieżący timestamp. Webhook nie jest już wywoływany.

Aby ponownie aktywować endpoint po dezaktywacji:

1. Sprawdź dlaczego dostarczenia padały (logi serwera, monitoring)
2. Napraw problem (np. przywróć endpoint, zwiększ pojemność)
3. Wyślij PATCH /webhooks/{id} z {"is_active": true} (co zresetuje failure_count)
4. Opcjonalnie wykonaj test: POST /webhooks/{id}/test

Pola monitorujące

Pole	Opis
failure_count	Licznik kolejnych nieudanych dostarczeń (resetowany przy sukcesie)
last_triggered_at	Ostatnia próba dostarczenia
last_success_at	Ostatnie udane dostarczenie
last_failure_at	Ostatnie nieudane dostarczenie
disabled_at	Data automatycznej dezaktywacji (null jeśli aktywny)

Idempotentność

ostrzeżenie

Twój endpoint musi być idempotentny. Z powodu retry, sieci lub timeoutów może otrzymać to samo zdarzenie wielokrotnie. Wielokrotne przetworzenie tego samego zdarzenia nie powinno powodować błędów ani duplikatów.

Implementacja idempotentności

Najprostszym sposobem jest deduplikacja po X-Webhook-Id:

<?php
$webhookId = $_SERVER['HTTP_X_WEBHOOK_ID'] ?? '';

// Sprawdź czy zdarzenie zostało już przetworzone
if (alreadyProcessed($webhookId)) {
    http_response_code(200);
    exit('Already processed');
}

// Przetwarzaj webhook...
processEvent($event);

// Oznacz jako przetworzone
markAsProcessed($webhookId);

http_response_code(200);
echo 'OK';

Alternatywa - deduplikacja po sesji + statusie

<?php
$sessionId = $event['data']['verification_session_id'];
$status = $event['data']['status'];

$existing = getOrder($sessionId);

if ($existing && $existing['status'] === 'verified') {
    // Już zweryfikowane - nic nie rób
    http_response_code(200);
    exit('OK');
}

// Aktualizuj status
updateOrderStatus($sessionId, $status);
http_response_code(200);

Dobre praktyki

• Odpowiadaj szybko (< 1s) - zrób tylko absolutnie niezbędne rzeczy synchronicznie, resztę kolejkuj asynchronicznie
• Używaj kolejki (Redis, RabbitMQ, SQS) - przyjmij webhook, wrzuć do kolejki, odpowiedz 200, przetwarzaj w workerze
• Loguj webhooks - zapisuj X-Webhook-Id, payload i czas odpowiedzi do diagnostyki
• Monitoruj failure_count - alarmuj jeśli webhook ma > 5 błędów z rzędu
• Testuj przed produkcją - użyj POST /webhooks/{id}/test aby zweryfikować konfigurację
• Weryfikuj podpis ZAWSZE - patrz Podpis HMAC

Co gdy webhook nie dotarł?

Jeśli z jakiegoś powodu webhook nie dotarł (np. Twój endpoint był wyłączony przez >36 minut), zawsze możesz:

1. Polling - okresowo sprawdzaj status sesji przez GET /verifications/{id}
2. Reconciliation - codzienne porównanie listy sesji z GET /verifications z lokalną bazą
3. Panel - ręczne odpytanie wyniku w panelu administracyjnym

Webhooks są najszybszą metodą ale nie są jedynym źródłem prawdy.