Documentación interactiva de la API pública.
La cabecera X-GenStudio-Signature puede llevar MÁS DE UN valor v1. Durante la ventana de gracia de 24 horas de la rotación del secreto lleva dos: uno firmado con el secreto nuevo y otro con el anterior. Pruébalos uno a uno y acepta la petición si CUALQUIERA coincide. Las implementaciones que leen un solo v1 rechazarán todas las entregas durante una rotación.
Rechaza las peticiones cuyo t difiera más de 5 minutos de tu hora actual. El contenido firmado es "{t}.{rawBody}": la marca de tiempo va dentro de la firma, así que no puede modificarse sin invalidarla.
X-GenStudio-Signature: t=1785000000,v1=<hex>,v1=<hex>
X-GenStudio-Event: generation.succeeded
X-GenStudio-Delivery: <delivery id>
X-GenStudio-Event-Version: 1POST /api/v1/me/webhook-endpoints/{id}/rotate-secret devuelve el nuevo secreto una sola vez. El secreto anterior sigue funcionando durante una ventana de gracia para que puedas desplegar sin perder entregas; la respuesta indica cuánto dura.
Rotar dos veces dentro de la ventana de gracia invalida INMEDIATAMENTE el secreto más antiguo. El endpoint guarda exactamente un secreto anterior, así que una segunda rotación lo sobrescribe. Termina de desplegar una rotación antes de empezar la siguiente.
Las URL de webhook deben usar https en el puerto 443. Si te autoalojas en otro puerto, termina TLS detrás de un proxy inverso en el 443, o usa un túnel como ngrok o Cloudflare Tunnel: ambos terminan en el 443, así que el desarrollo local funciona sin cambios.
Rotar el secreto y volver a lanzar la verificación solo están disponibles en la aplicación web. Ambos exigen volver a introducir la contraseña, y una clave de API no tiene contexto de contraseña. Es una decisión de alcance deliberada del MVP, no un endpoint que falte.
Un mismo evento se entrega como máximo 9 veces, repartidas a lo largo de al menos 31 horas. Dimensiona tu ventana de deduplicación en consecuencia: el mismo id X-GenStudio-Delivery puede llegar varias veces en ese periodo.
Deduplica por X-GenStudio-Delivery, no por el cuerpo del mensaje. El id de entrega es el mismo en todos los reintentos del evento; la firma no lo es (cada intento se firma con una marca de tiempo nueva).
Responde con cualquier 2xx para confirmar. Cualquier otra cosa —incluido un cuerpo de respuesta lento— cuenta como intento fallido y se reintenta. Tras el último intento la entrega se marca como dead y puedes reenviarla desde el registro.
anon_trial_unavailable — 503 — El acceso de prueba anónimo no está disponible temporalmente. Vuelve a intentarlo más tarde, o regístrate para obtener una cuenta completa.asset_lost — 410 — Este archivo ya no está disponible. Se te han devuelto los créditos.download_timeout — 504 — No pudimos recuperar el resultado a tiempo. Se te han devuelto los créditos.endpoint_not_verified — 409 — Este endpoint de webhook aún no se ha verificado.forbidden — 403 — Tu cuenta está autenticada pero no tiene permiso para realizar esta acción.idempotency_key_reuse — 422 — Esta clave de idempotencia ya se usó con una solicitud diferente.insufficient_credits — 402 — Necesitas {required} créditos, pero solo tienes {available}.insufficient_credits_on_fallback — 402 — El modelo alternativo necesita {required} créditos, pero solo hay {available}. Se te han devuelto los créditos.internal_error — 500 — Se produjo un error interno inesperado.invalid_credentials — 401 — Error al iniciar sesión. Revisa la dirección y la contraseña, y comprueba que la dirección esté verificada.invalid_params — 422 — Algunos ajustes no son válidos.invalid_state — 422 — Esta acción no está permitida en el estado actual.invite_invalid — 422 — Ese código de invitación no se puede usar. Pide otro a quien te invitó.job_stalled — 500 — Este trabajo nunca comenzó. Se te han devuelto los créditos.job_stuck — 500 — Este trabajo dejó de avanzar. Se te han devuelto los créditos.maintenance — 503 — Las nuevas generaciones están en pausa por mantenimiento programado. Las tareas en curso terminarán y tu historial sigue disponible. Vuelve a intentarlo en unos minutos.not_found — 404 — El recurso solicitado no existe o no es visible para ti.provider_auth_failed — 500 — El servicio está mal configurado y no puede conectar con el proveedor. Se te han devuelto los créditos. Escribe a support@yaspost.com.rate_limited — 429 — Demasiados intentos. Inténtalo un poco más tarde.reauth_required — 401 — Vuelve a introducir tu contraseña para continuar.submit_unknown — 500 — No pudimos confirmar si este trabajo se envió. Se te han devuelto los créditos.subscription_required — 403 — Esta función está disponible solo para suscriptores. Mejora tu plan para usarla.unauthorized — 401 — Tu sesión ya no es válida. Inicia sesión de nuevo.upload_too_large — 413 — El archivo supera el límite de {maxBytes} bytes.upstream_error — 502 — El proveedor devolvió un error. Se te han devuelto los créditos.upstream_rate_limited — 502 — El proveedor está ocupado. Inténtalo de nuevo en un momento. Se te han devuelto los créditos.upstream_rejected — 502 — El proveedor rechazó esta generación. Se te han devuelto los créditos.upstream_timeout — 504 — El proveedor tardó demasiado. Se te han devuelto los créditos.upstream_unavailable — 502 — El proveedor no está disponible temporalmente. Inténtalo de nuevo más tarde. Se te han devuelto los créditos.verification_failed — 422 — Ese código no coincide. Solicita uno nuevo.