Como funciona
Configure uma URL HTTPS de notificação para que sua aplicação receba mudanças relevantes da operação. O webhook deve alimentar o estado interno do pedido, cobrança ou processo correspondente.
Fluxo recomendado
Uma transação ou evento relevante evolui no processamento.
A aplicação recebe o payload no endpoint HTTPS configurado.
Guarde identificadores e conteúdo suficiente para rastreabilidade.
Pedido, ERP, OMS, financeiro e automações seguem o novo estado.
Estrutura da notificação
Os eventos transacionais informam o identificador da transação, tipo do evento, status, referência da operação, seller e assinatura da notificação.
{
"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 e transaction.void.succeeded.Implementação
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 deve seguir o contrato vigente da integração antes de o evento ser considerado confiável.Idempotência e robustez
Não processe duas vezes.
Webhooks podem ser reenviados. Garanta que o mesmo evento não produza efeitos duplicados na sua aplicação.
Acknowledge rápido.
Evite operações longas antes de retornar HTTP 200 ao webhook.
Valide o estado atual.
Não dependa apenas da ordem de chegada; compare o evento com o estado conhecido.
Guarde histórico.
Registre recebimento, processamento, erro e correlação com pedido/transação.
Checklist
- URL HTTPS configurada e acessível externamente.
- Timeout baixo e processamento pesado em fila.
- Validação de
sign_confirm. - Idempotência para evitar efeitos duplicados.
- Logs com
id,type,reference_ideio_seller_id. - Alertas para falhas repetidas de processamento.
- Rotina de reconciliação por consulta à API para casos excepcionais.