IOPAY→Desarrolladores→Webhooks
Eventos y sincronización

Webhooks y notificaciones

Organice la recepción de cambios de estatus y conecte pagos a sus propios sistemas sin depender de la votación continua.

Punto finalHTTPS
El patrónSincronización
ObjetivoSincronizar estado
Flujo recomendado Ejemplo de manipulador Los credenciales
Concepto

Cómo funciona

Configure una URL HTTPS de notificación para que su aplicación reciba cambios relevantes de la operación. El webhook deberá proporcionar el estado interno de la solicitud, cobro o proceso correspondiente.

Configuración actual. La URL se define en Configuraciones → Transacciones en línea. Sólo se acepta HTTPS. En caso de que la solicitud o respuesta sea diferente de 200, la documentación actual informa de 3 intentos más.
Flujo recomendado

Flujo recomendado

01 · IOPAYEl estado cambia.

Una transacción o evento relevante evoluciona en el procesamiento.

02 · EndpointSu webhook recibe.

La aplicación recibe la carga de pago en el punto final HTTPS configurado.

03 · PersistenciaRegistra el evento.

Guarde identificadores y contenido suficiente para su rastreabilidad.

04 · DominioActualice los sistemas.

En la orden, ERP, OMS, finanzas y automatización siguen el nuevo estado.

Implementación

Implementación

Ejemplo conceptual · 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. El ejemplo es arquitectónico. La validación, la firma, los campos y las reglas de retiro deberán seguir el contrato de integración vigente.
Robustez y seguridad

Idempotencia y robustez

El tiempo de trabajo

No proceses dos veces.

Use un identificador de evento/transación para evitar efectos duplicados.

Respuesta

Reconocimiento rápido.

Evite operaciones largas antes de devolver el éxito al emisor del evento.

El orden

Valida el estado actual.

No depende sólo del orden de llegada; compara el evento con el estado conocido.

Observabilidad

Guarde el historial.

Registre la recepción, el procesamiento, el error y la correlación con la solicitud/transación.

Lista de control

Lista de control

  • URL HTTPS configurada y accesible externamente.
  • Tiempo de espera bajo y procesamiento pesado en fila.
  • Idempotencia por evento/transación.
  • Los registros con correlación de solicitud y identificador IOPAY.
  • Alertas de fallas de procesamiento repetidas.
  • Routine de conciliación por consulta a API para casos excepcionales.