Jak to działa
Skonfiguruj adres URL HTTPS powiadomień, aby Twoja aplikacja otrzymywała istotne zmiany w operacji. Webhook powinien zasilać wewnętrzny stan odpowiedniego zamówienia, płatności lub procesu.
Zalecany przepływ
Transakcja lub istotne zdarzenie postępuje w przetwarzaniu.
Aplikacja odbiera payload w skonfigurowanym endpoincie HTTPS.
Zapisz identyfikatory i wystarczającą treść dla identyfikowalności.
Zamówienie, ERP, OMS, finanse i automatyzacje podążają za nowym stanem.
Struktura powiadomienia
Zdarzenia transakcyjne zawierają identyfikator transakcji, typ zdarzenia, status, odniesienie operacji, sellera i podpis powiadomienia.
{
"id": "8774b47d26d54a0b9138cde9d8cc421f",
"type": "transaction.succeeded",
"status": "succeeded",
"reference_id": "order_102938",
"io_seller_id": "<IO_SELLER_ID>",
"sign_confirm": "iopay::<SIGNATURE>"
}transaction.created, transaction.pending, transaction.succeeded, transaction.failed, transaction.disputed i transaction.void.succeeded.Implementacja
Route::post('/webhooks/iopay', function (Request $request) {
$payload = $request->all();
// Identificador da transação
$transactionId = $payload['id'] ?? null;
// Ex.: transaction.succeeded
$eventType = $payload['type'] ?? null;
// Ex.: succeeded
$status = $payload['status'] ?? null;
// Referência enviada na criação da transação
$referenceId = $payload['reference_id'] ?? null;
// 1. valide sign_confirm conforme o contrato vigente
// 2. garanta idempotência antes de aplicar efeitos
// 3. persista o evento para rastreabilidade
// 4. processe operações pesadas de forma assíncrona
ProcessIopayWebhook::dispatch($payload);
return response()->json(['received' => true], 200);
});sign_confirm musi być zgodna z aktualnym kontraktem integracji, zanim zdarzenie zostanie uznane za wiarygodne.Idempotentność i odporność
Nie przetwarzaj dwa razy.
Webhooki mogą być wysyłane ponownie. Upewnij się, że to samo zdarzenie nie wywoła zdublowanych efektów w Twojej aplikacji.
Szybkie potwierdzenie.
Unikaj długich operacji przed zwróceniem HTTP 200 do webhooka.
Zweryfikuj bieżący stan.
Nie polegaj wyłącznie na kolejności przybycia; porównaj zdarzenie ze znanym stanem.
Zachowaj historię.
Rejestruj odbiór, przetwarzanie, błędy i powiązanie z zamówieniem/transakcją.
Lista kontrolna
- URL HTTPS skonfigurowany i dostępny z zewnątrz.
- Krótki timeout i ciężkie przetwarzanie w kolejce.
- Walidacja
sign_confirm. - Idempotentność, aby uniknąć zdublowanych efektów.
- Logi z
id,type,reference_idiio_seller_id. - Alerty dla powtarzających się błędów przetwarzania.
- Rutyna uzgadniania przez zapytania do API w wyjątkowych przypadkach.