IOPAY→Developers→Webhooks
Events & timing

Webhooks & notifications

Organize the receipt of status changes and connect payments to your own systems without relying on continuous polling.

EndpointHTTPS
StandardAsynchronous
GoalSynchronize state
Recommended flow Example of handler Credentials
Concept

How it works

Set up an HTTPS notification URL so that your application receives relevant changes from the operation. The webhook shall feed the internal status of the application, collection or corresponding process.

Current settings. The URL is set to The following is a list of the main activities of the European Investment Bank:. Only HTTPS is accepted. In the event of failure of a different request or response of 200, the current documentation reports 3 more attempts.
Recommended flow

Recommended flow

01 · IOPAYStatus is changing.

A relevant transaction or event evolves in the processing.

02 · EndpointYour webhook receives.

The application receives the payload at the configured HTTPS endpoint.

03 · PersistenceRecord the event.

Keep identifiers and enough traceability content.

04 · DomainUpdating the systems.

On demand, ERP, WHO, finance and automation are following the new trend.

Implementation of the programme

Implementation of the programme

Conceptual example · Laravel
Route::post('/webhooks/iopay', function (Request $request) {
    $payload = $request->all();

    // 1. valide a origem / assinatura conforme o contrato vigente
    // 2. persista o evento com identificador único
    // 3. responda rapidamente
    ProcessIopayWebhook::dispatch($payload);

    return response()->json(['received' => true], 200);
});
Importante. The example is architectural. Validation, signature, fields and retry rules shall follow the current integration contract.
Robustness

Impotence and robustness

Impotence

Don't sue me twice.

Use an event/transaction identifier to prevent duplicate effects.

Answer

Acknowledge quickly.

Avoid long operations before returning the event successfully to the issuer.

Order

Valid the current status.

Do not just depend on the order of arrival; compare the event with the known state.

Observability

Keep the history.

Record receipt, processing, error and correlation with request/transaction.

Checklist of the

Checklist of the

  • HTTPS URL configured and externally accessible.
  • Low timeout and heavy processing in line.
  • Idempt by event/transaction
  • Logs with the request correlation and identifier IOPAY.
  • Alerts for repeated processing failures.
  • Reconciliation routine by consultation with API for exceptional cases.