So funktioniert es
Richten Sie eine HTTPS-Benachrichtigungs-URL ein, damit Ihre Anwendung relevante Änderungen im Betrieb erhält. Der Webhook sollte den internen Status der entsprechenden Bestellung, Zahlung oder des Prozesses speisen.
Empfohlener Ablauf
Eine Transaktion oder ein relevantes Ereignis entwickelt sich in der Verarbeitung weiter.
Die Anwendung empfängt den Payload am konfigurierten HTTPS-Endpunkt.
Speichern Sie Kennungen und ausreichend Inhalt für die Nachverfolgbarkeit.
Bestellung, ERP, OMS, Finanzen und Automatisierungen folgen dem neuen Status.
Struktur der Benachrichtigung
Transaktionsereignisse enthalten Transaktionskennung, Ereignistyp, Status, Referenz des Vorgangs, Seller und Signatur der Benachrichtigung.
{
"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 und transaction.void.succeeded.Implementierung
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 muss dem aktuellen Integrationsvertrag folgen, bevor das Ereignis als vertrauenswürdig gilt.Idempotenz und Robustheit
Nicht doppelt verarbeiten.
Webhooks können erneut gesendet werden. Stellen Sie sicher, dass dasselbe Ereignis in Ihrer Anwendung keine doppelten Effekte erzeugt.
Schnelle Bestätigung.
Vermeiden Sie lange Vorgänge, bevor Sie dem Webhook HTTP 200 zurückgeben.
Aktuellen Status prüfen.
Verlassen Sie sich nicht nur auf die Eingangsreihenfolge; vergleichen Sie das Ereignis mit dem bekannten Status.
Verlauf speichern.
Erfassen Sie Empfang, Verarbeitung, Fehler und Zuordnung zu Bestellung/Transaktion.
Checkliste
- HTTPS-URL konfiguriert und von außen erreichbar.
- Kurzer Timeout und rechenintensive Verarbeitung in einer Warteschlange.
- Validierung von
sign_confirm. - Idempotenz zur Vermeidung doppelter Effekte.
- Logs mit
id,type,reference_idundio_seller_id. - Warnungen bei wiederholten Verarbeitungsfehlern.
- Abstimmungsroutine per API-Abfrage für Ausnahmefälle.