Miten se toimii
Määritä HTTPS-ilmoitus-URL, jotta sovelluksesi vastaanottaa toiminnan olennaiset muutokset. Webhookin tulee päivittää vastaavan tilauksen, veloituksen tai prosessin sisäinen tila.
Suositeltu virta
Tapahtuma tai olennainen muutos etenee käsittelyssä.
Sovellus vastaanottaa payloadin määritettyyn HTTPS-päätepisteeseen.
Tallenna tunnisteet ja riittävä sisältö jäljitettävyyttä varten.
Tilaus, ERP, OMS, talous ja automaatiot seuraavat uutta tilaa.
Ilmoituksen rakenne
Tapahtumailmoitukset sisältävät tapahtuman tunnisteen, tapahtumatyypin, tilan, toiminnan viitteen, myyjän ja ilmoituksen allekirjoituksen.
{
"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 ja transaction.void.succeeded.Toteutus
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-validoinnin on noudatettava integraation voimassa olevaa sopimusta ennen kuin tapahtumaa pidetään luotettavana.Idempotenssi ja vankkuus
Älä käsittele kahdesti.
Webhookeja voidaan lähettää uudelleen. Varmista, ettei sama tapahtuma aiheuta päällekkäisiä vaikutuksia sovelluksessasi.
Nopea kuittaus.
Vältä pitkiä toimintoja ennen HTTP 200 -vastauksen palauttamista webhookille.
Tarkista nykyinen tila.
Älä luota pelkkään saapumisjärjestykseen; vertaa tapahtumaa tunnettuun tilaan.
Säilytä historia.
Kirjaa vastaanotto, käsittely, virheet ja yhteys tilaukseen/tapahtumaan.
Checklist
- HTTPS-URL määritetty ja ulkoisesti saavutettavissa.
- Lyhyt aikakatkaisu ja raskas käsittely jonossa.
sign_confirm-validointi.- Idempotenssi päällekkäisten vaikutusten välttämiseksi.
- Lokit, joissa
id,type,reference_idjaio_seller_id. - Hälytykset toistuvista käsittelyvirheistä.
- Täsmäytysrutiini API-kyselyillä poikkeustapauksiin.