IOPAY→Developers→Webhooks
Events & synchronization

Webhooks & notifications

Organize how you receive status changes and connect payments to your own systems without relying on continuous polling.

EndpointHTTPS
PatternAsynchronous
GoalSynchronize state
Recommended flow Handler example Credentials →
Concept

How it works

Set up an HTTPS notification URL so your application receives relevant changes in the operation. The webhook should feed the internal state of the corresponding order, charge or process.

Current setup. The URL is defined in Settings → Online Transactions. Only HTTPS is accepted. On a request failure or a response other than 200, the current documentation states 3 more attempts.
Recommended flow

Recommended flow

01 · IOPAYStatus changes.

A transaction or relevant event progresses in processing.

02 · EndpointYour webhook receives it.

The application receives the payload at the configured HTTPS endpoint.

03 · PersistenceRecord the event.

Store identifiers and enough content for traceability.

04 · DomainUpdate systems.

Order, ERP, OMS, finance and automations follow the new state.

Payload

Notification structure

Transactional events provide the transaction identifier, event type, status, operation reference, seller and notification signature.

Example · transaction.succeeded
{
  "id": "8774b47d26d54a0b9138cde9d8cc421f",
  "type": "transaction.succeeded",
  "status": "succeeded",
  "reference_id": "order_102938",
  "io_seller_id": "<IO_SELLER_ID>",
  "sign_confirm": "iopay::<SIGNATURE>"
}
Events. Transactional events include transaction.created, transaction.pending, transaction.succeeded, transaction.failed, transaction.disputed and transaction.void.succeeded.
Implementation

Implementation

Conceptual example · Laravel
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);
});
Important. The example is architectural. Validation of sign_confirm must follow the integration's current contract before the event is considered trustworthy.
Robustness

Idempotency and robustness

Idempotency

Don't process twice.

Webhooks can be resent. Make sure the same event doesn't produce duplicate effects in your application.

Response

Quick acknowledgment.

Avoid long operations before returning HTTP 200 to the webhook.

Order

Validate the current state.

Don't rely only on arrival order; compare the event with the known state.

Observability

Keep history.

Record receipt, processing, errors and correlation with order/transaction.

Checklist

Checklist

  • HTTPS URL configured and externally reachable.
  • Low timeout and heavy processing in a queue.
  • Validation of sign_confirm.
  • Idempotency to avoid duplicate effects.
  • Logs with id, type, reference_id and io_seller_id.
  • Alerts for repeated processing failures.
  • Reconciliation routine via API queries for exceptional cases.