Configuracion
Configura tu webhook en el dashboard o envia webhook_url como override por request. En produccion, el webhook debe existir antes de enviar requests.
El webhook es el patron principal. El polling es un complemento, no un reemplazo.
factura.completed
Payload
{
"event": "factura.completed",
"version": "2026-03",
"idempotency_key": "factura.completed:id_abc123:1741132800",
"session_id": "id_abc123",
"external_id": "expense_12345",
"status": "completed",
"completed_at": "2026-03-06T12:01:23Z",
"processing_time_seconds": 34,
"files": {
"xml_url": "https://api.facturagpt.com.mx/api/v1/files/id_abc123/xml",
"pdf_url": "https://api.facturagpt.com.mx/api/v1/files/id_abc123/pdf"
}
}factura.failed
Payload
{
"event": "factura.failed",
"version": "2026-03",
"session_id": "id_abc123",
"external_id": "expense_12345",
"status": "failed",
"reason_code": "PORTAL_UNAVAILABLE",
"reason_message": "The merchant portal was inaccessible after multiple attempts."
}Buenas practicas
- Responde 200 OK rapido.
- Guarda el payload antes de procesarlo.
- Deduplica con idempotency_key.
- Haz tu handler idempotente porque puede haber reintentos.
Verificacion de firma
Usa el secreto del dashboard para validar que la request realmente viene de FacturaGPT. Revisa headers como x-facturagpt-signature y x-facturagpt-timestamp.