Cómo funciona
Configura una URL HTTPS de notificación para que tu aplicación reciba los cambios relevantes de la operación. El webhook debe alimentar el estado interno del pedido, cobro o proceso correspondiente.
Flujo recomendado
Una transacción o evento relevante avanza en el procesamiento.
La aplicación recibe el payload en el endpoint HTTPS configurado.
Guarda identificadores y contenido suficiente para la trazabilidad.
Pedido, ERP, OMS, finanzas y automatizaciones siguen el nuevo estado.
Estructura de la notificación
Los eventos transaccionales informan el identificador de la transacción, el tipo de evento, el estado, la referencia de la operación, el seller y la firma de la notificación.
{
"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 y transaction.void.succeeded.Implementación
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 debe seguir el contrato vigente de la integración antes de considerar fiable el evento.Idempotencia y robustez
No proceses dos veces.
Los webhooks pueden reenviarse. Asegúrate de que el mismo evento no produzca efectos duplicados en tu aplicación.
Acknowledge rápido.
Evita operaciones largas antes de devolver HTTP 200 al webhook.
Valida el estado actual.
No dependas solo del orden de llegada; compara el evento con el estado conocido.
Guarda el historial.
Registra recepción, procesamiento, error y correlación con pedido/transacción.
Checklist
- URL HTTPS configurada y accesible externamente.
- Timeout bajo y procesamiento pesado en cola.
- Validación de
sign_confirm. - Idempotencia para evitar efectos duplicados.
- Logs con
id,type,reference_ideio_seller_id. - Alertas para fallos repetidos de procesamiento.
- Rutina de reconciliación mediante consultas a la API para casos excepcionales.