Webhooks en localhost: probar callbacks de verificación sin un endpoint público

El problema y su decisión

En localhost, un callback inalcanzable se ve igual que un proveedor lento: la sesión queda pendiente. El atajo arriesgado es aprobar usuarios manualmente o tratar un tiempo agotado como éxito para poder seguir desarrollando. La decisión que tiene delante es más acotada. ¿Prueba las transiciones de estado localmente, por separado de la entrega por red? ¿O necesita un sandbox real con túnel antes de poder confiar en su lógica? El fixture respalda el primer camino. Ejercita su manejo de estado sin URL pública, sin credenciales y sin llamadas de red. No prueba la entrega real, las firmas ni los reintentos del proveedor.

Lo que implementa el fixture

La clase Identity guarda sesiones y eventos en SQLite. create() exige identificadores que empiecen por fixture- y acepta un timeout entre 1 y 3600 segundos. Guarda el estado pending y fija deadline como now más el timeout. Devuelve un hosted_link que apunta a example.invalid, con link_executable false. event() solo acepta mode synthetic_fixture y source fixture_callback. Cualquier otro mode o source lanza PRODUCTION_SIGNATURE_VERIFIER_NOT_IMPLEMENTED. Los ID de evento también deben empezar por fixture-. recover() marca como expired una sesión pending, review o unknown una vez superado deadline. Devuelve provider_polled false. Expira la sesión localmente y nunca consulta a un proveedor.

Escenario hipotético resuelto

Hipotéticamente, una desarrolladora ejecuta la incorporación en su portátil. Se crea una sesión en now=0 con timeout 60, así que deadline es 60. Ningún callback puede llegar a localhost. La desarrolladora no espera a la red. En su lugar, inyecta un evento sintético, fixture-approved, con estado Approved y policy true. La lectura devuelve status approved, permission_granted true, grant_count 1, policy_version 1, allow_action true y live_permission_changed false. Reenviar el mismo evento devuelve el registro idéntico, por lo que grant_count sigue en 1. Un evento Declined posterior devuelve status declined y permission_granted false, con grant_count todavía en 1. En una segunda ejecución no llega ningún callback y se llama a recover con now=61. El resultado es status expired, permission_granted false, grant_count 0, next review_or_authorized_provider_refresh y provider_polled false.

Manejo de fallos

Un evento para una sesión desconocida, o con un tenant o subject equivocado, lanza BINDING_MISMATCH. Leer una sesión que no existe lanza SESSION_NOT_FOUND. Un estado no reconocido lleva la sesión a unknown, nunca a approved. Un evento que llega después del plazo produce expired. Los eventos sobre sesiones ya finalizadas no las reabren; la única excepción es una corrección Declined sobre una sesión approved. Su aplicación debe tratar cada uno de estos casos como motivo de revisión, no como un reintento que acabe concediendo acceso. Incluso un resultado concedido es un registro local del fixture: live_permission_changed es siempre false.

Diseño propuesto frente al comportamiento del fixture

Todo lo anterior es comportamiento implementado en el fixture. Lo siguiente es un diseño propuesto que usted tendría que construir y verificar por su cuenta. Primero, exponga una ruta de desarrollo, o un túnel que esté autorizado a usar, solo para tráfico de sandbox. Segundo, añada validación de firma específica del proveedor. Tercero, realice una reconciliación de estado acotada y autorizada cuando venza el plazo, en lugar de limitarse a expirar la sesión. Por último, decida los permisos de negocio con sus propias reglas. Los métodos decide() y revise_policy() del fixture ilustran una aprobación explícita y versionada, pero un permiso sintético no es un permiso de negocio real. El ejemplo descargable tiene cuatro ramas para comprobaciones de teléfono más el flujo de identidad. No es lo mismo que la prueba HTTP anónima de tres escenarios.

Lista de aceptación

Ejecute las pruebas de reinicio y de timeout indicadas en la guía. Reinicie con la misma base de datos SQLite y confirme que el estado pendiente se conserva. Confirme que un evento duplicado deja grant_count en 1. Confirme que recover después del plazo devuelve expired con provider_polled false. Confirme que se rechazan las fuentes que no son del fixture. Confirme que ninguna ruta de código convierte un callback ausente en approved. Antes de cualquier sandbox real, registre lo que queda sin demostrar: verificación de firmas, entrega y reintentos reales, reconciliación y permisos reales de usuarios. Después decida si una solicitud de sandbox guardada encaja con su tarea.

Ejecutar el ejemplo sintético comprobado

Descargue y extraiga https://gridzen.ai/downloads/verification-delivery.zip, entre en verification_delivery y ejecute con Python 3.10+. El ejemplo local no hace llamadas de red. Use una base nueva para otra prueba de identidad.

python3 delivery.py identity --db /tmp/gridzen-article-fixture.sqlite

Fuentes y alcance

https://gridzen.ai/guides/missing-verification-webhook/ https://gridzen.ai/guides/current-capabilities/ Basado en las fuentes comprobadas y el ejemplo local; las reglas propuestas son recomendaciones de diseño, no comportamiento de producción demostrado. Redacción asistida por IA con revisión independiente.