Payloads de Webhooks
Ejemplos de payloads enviados para cada tipo de evento. Todos los webhooks se envian como HTTP POST con Content-Type: application/json.
Headers de seguridad
Cada notificacion incluye los headers X-Owem-Signature (HMAC-SHA256), X-Owem-Timestamp, X-Owem-Event-Id y X-Owem-Event-Type. Consulte Webhooks — Vision General para detalles sobre validacion.
Referencia de Estados
No todos los eventos significan que la transaccion esta completa. Use la tabla a continuacion para saber cuando los fondos han sido efectivamente liquidados.
| Evento | Estado | Significado | Fondos liquidados? |
|---|---|---|---|
pix.charge.created | created | Codigo QR generado o cash-in iniciado. Esperando pago. | No — solo creado |
pix.charge.paid | paid | PIX recibido y liquidado en cuenta. Saldo actualizado, tarifa cobrada. | Si |
pix.charge.expired | expired | Codigo QR expirado sin pago. | N/A |
pix.charge.cancelled | cancelled | Codigo QR cancelado antes del pago. | N/A |
pix.payout.processing | processing | PIX enviado, esperando confirmacion del destino. Saldo reservado (hold). | No — puede revertir |
pix.payout.confirmed | settled | PIX enviado confirmado por el destino. Debito definitivo. | Si |
pix.payout.failed | rejected | PIX enviado rechazado por el destino. Hold liberado, saldo restaurado. | No |
pix.payout.returned | returned | PIX enviado devuelto despues de la liquidacion. | Si (reverso) |
pix.refund.requested | requested | Devolucion PIX solicitada (MED o voluntaria). Reserva creada. | Parcial |
pix.refund.completed | completed | Devolucion PIX completada y liquidada. Debito definitivo. | Si |
pix.return.received | received | Devolucion PIX recibida (credito en cuenta). | Si |
webhook.test | test | Evento de prueba activado manualmente. | N/A |
Regla: Para reconciliacion financiera, solo considere como definitivos los estados paid, settled, received o completed. Todos los demas son intermediarios.
Campos comunes
Todos los payloads de webhook incluyen estos campos:
| Campo | Tipo | Descripcion |
|---|---|---|
event_type | string | Tipo de evento que disparo el webhook (ej: pix.charge.paid) |
status | string | Estado de la operacion — consulte la Referencia de Estados |
account_id | integer | Numero de su cuenta en Owem |
entity_id | string (UUID) | Identificador de entidad Owem |
Valores monetarios: Todos los valores estan en subcentavos (1 BRL = 10.000 subcentavos). Para convertir a reales: valor / 10000. Ejemplo: 300000 / 10000 = R$ 30,00.
pix.charge.paid
Enviado cuando un PIX es recibido y liquidado en la cuenta. Este es el evento que confirma que el dinero llego.
Ejemplo — vinculado a codigo QR
{
"event_type": "pix.charge.paid",
"status": "paid",
"account_id": 10014,
"amount": 300000,
"fee_amount": 400,
"end_to_end_id": "E9040088820260402095758709999671",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"tx_id": "u5f26sfyrq4plkw7tjwa",
"counterparty_name": "MARIA SANTOS",
"paid_at": "2026-04-02T09:58:05Z"
}Ejemplo — transferencia directa (sin QR)
{
"event_type": "pix.charge.paid",
"status": "paid",
"account_id": 10014,
"amount": 300000,
"fee_amount": 400,
"end_to_end_id": "E9040088820260402095758709999671",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"tx_id": null,
"counterparty_name": "JOAO SILVA",
"paid_at": "2026-04-02T10:15:22Z"
}| Campo | Tipo | Descripcion |
|---|---|---|
event_type | string | Siempre pix.charge.paid |
status | string | Siempre paid |
account_id | integer | Numero de cuenta que recibio el PIX |
amount | integer | Valor recibido en subcentavos. 300000 = R$ 30,00 |
fee_amount | integer | Tarifa cobrada en subcentavos. 400 = R$ 0,04 |
end_to_end_id | string | Identificador E2E del BACEN (unico por transaccion PIX) |
entity_id | string (UUID) | Identificador de entidad Owem |
tx_id | string o null | ID de transaccion. Presente cuando vinculado a un codigo QR. null para transferencias directas |
counterparty_name | string o null | Nombre del pagador (remitente) |
paid_at | string (ISO 8601) | Fecha/hora de liquidacion (UTC) |
pix.charge.created
Enviado cuando un codigo QR es generado o un cash-in es iniciado. Ningun movimiento financiero ha ocurrido.
{
"event_type": "pix.charge.created",
"status": "created",
"account_id": 10014,
"amount": 500000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"tx_id": "abc123def456ghi789"
}pix.payout.confirmed
Enviado cuando un PIX enviado es confirmado por la institucion destino. Debito definitivo.
{
"event_type": "pix.payout.confirmed",
"status": "settled",
"account_id": 10014,
"amount": 500000,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"pix_key": "destinatario@email.com",
"description": "Pago proveedor"
}pix.payout.processing
Enviado cuando un PIX enviado esta siendo procesado. El saldo esta reservado (hold) pero no es definitivo.
{
"event_type": "pix.payout.processing",
"status": "processing",
"account_id": 10014,
"amount": 500000,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7"
}pix.payout.failed
Enviado cuando un PIX enviado es rechazado. Hold liberado, saldo restaurado.
{
"event_type": "pix.payout.failed",
"status": "rejected",
"account_id": 10014,
"amount": 500000,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"error_reason": "Cuenta destinatario no encontrada"
}pix.refund.completed
Enviado cuando una devolucion PIX es procesada y completada.
{
"event_type": "pix.refund.completed",
"status": "completed",
"account_id": 10014,
"amount": 300000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"original_end_to_end_id": "E9040088820260402095758709999671",
"return_code": "MD06"
}pix.return.received
Enviado cuando una devolucion PIX es recibida (credito en cuenta).
{
"event_type": "pix.return.received",
"status": "received",
"account_id": 10014,
"amount": 300000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"return_e2e_id": "D9040088820260402111500000001",
"original_e2e_id": "E9040088820260402095758709999671",
"return_code": "MD06"
}webhook.test
Evento de prueba activado manualmente para validar la configuracion del webhook.
{
"event_type": "webhook.test",
"status": "test",
"account_id": 10014,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"message": "Webhook test event"
}Como interpretar los webhooks
Para confirmar que el dinero llego: Espere pix.charge.paid con status: "paid". Es el unico evento que garantiza que el valor fue acreditado y la tarifa cobrada.
Para confirmar que el dinero fue enviado: Espere pix.payout.confirmed con status: "settled". El estado processing es intermediario — el saldo esta reservado pero puede revertirse si es rechazado.
Para devoluciones: pix.return.received con status: "received" confirma credito en cuenta.
Deduplicacion: Use el header X-Owem-Event-Id o el campo end_to_end_id como clave de idempotencia.