Logo de X Image SplitterX Image Splitter
Logo de X Image SplitterX Image Splitter

Desarrolladores

Webhooks

Recibe notificaciones firmadas cuando terminan las generaciones, cambian los créditos o se completan los pagos, y verifica cada entrega.

Los webhooks envían un POST HTTPS a tu servidor cuando ocurre algo en tu cuenta, para que no tengas que consultar una y otra vez. Los endpoints se gestionan en Cuenta › Webhooks o con la API REST.

Eventos

EventoSe envía cuandoCampos de data
generation.queuedEmpieza una generaciónjob_id, creation_id, status, model_id
generation.completedUna generación termina correctamentejob_id, creation_id, status, model_id
generation.failedUna generación fallajob_id, creation_id, status, model_id, failure_code
credits.updatedCambia tu saldo de créditosbalance, credit_sequence
billing.payment_succeededSe completa un pagoinvoice_no, amount (unidades menores), currency, purchase_kind
subscription.updatedCambia tu suscripciónsubscription_no, status, plan_id, current_period_end
support_request.updatedSe actualiza una solicitud de soporterequest_id, kind, status

Las cargas solo contienen identificadores y estados, nunca prompts, URLs de archivos ni datos de contacto. Obtén el recurso completo con la API cuando lo necesites, por ejemplo GET /creations/{creationId} después de generation.completed.

Todas las entregas tienen el mismo envoltorio:

{
  "event_id": "…",
  "type": "generation.completed",
  "created_at": "2026-11-13T10:24:05.000Z",
  "schema_version": 1,
  "data": {
    "job_id": "…",
    "creation_id": "…",
    "status": "succeeded",
    "model_id": "seedream-5-5"
  }
}

Añade un endpoint

Registra la URL

En Cuenta › Webhooks, selecciona Añadir endpoint, escribe la URL del endpoint y elige los Eventos que enviar. La URL debe ser una dirección https pública.

Guarda el secreto de firma

El secreto de firma del endpoint (whsec_…) se muestra una sola vez, en Copia tu secreto de firma. Guárdalo con los secretos de tu servidor.

Verifica el endpoint

Un endpoint nuevo aparece como Sin verificar y no recibe nada hasta que lo verificas. Selecciona Verificar ahora: enviamos un evento firmado webhook.verification cuyo data contiene un challenge. Tu endpoint debe responder con un estado 2xx y el mismo valor en JSON:

{ "challenge": "<the value you received>" }

El desafío caduca a los pocos minutos. Si sale bien, el endpoint muestra Verificado y empieza a recibir eventos.

Verifica las firmas

Las entregas siguen la especificación Standard Webhooks. Cada petición lleva tres cabeceras:

  • webhook-id: el event_id del evento;
  • webhook-timestamp: cuándo se firmó este intento, en segundos Unix;
  • webhook-signature: la firma del cuerpo en bruto con el secreto de tu endpoint.

Verifica cada entrega sobre el cuerpo en bruto de la petición antes de confiar en ella. Cualquier biblioteca de Standard Webhooks lo hace y además rechaza las marcas de tiempo antiguas:

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.WEBHOOK_SECRET); // whsec_…

export async function handleWebhook(request: Request) {
  const body = await request.text();
  const event = webhook.verify(body, {
    'webhook-id': request.headers.get('webhook-id') ?? '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') ?? '',
    'webhook-signature': request.headers.get('webhook-signature') ?? '',
  }); // lanza un error si la firma no es válida

  if (event.type === 'webhook.verification') {
    return Response.json({ challenge: event.data.challenge });
  }
  // Procesa el evento y responde rápido.
  return new Response(null, { status: 204 });
}

Comportamiento de entrega

  • Responder con estado 2xx rápidamente: cualquier código 4xx/5xx, redirección, tiempo de espera o fallo de red se computa como entrega fallida. Traslada tareas pesadas a colas asíncronas en segundo plano tras enviar la respuesta HTTP.
  • Reintentos programados: las entregas fallidas se reintentan con intervalos exponenciales (~5s, 5m, 30m, 2h, 5h, 10h). Si el último intento falla, el estado pasa a Fallido.
  • Entrega at-least-once: un mismo evento puede recibirse más de una vez con idéntico event_id. Almacena los event_id procesados para garantizar idempotencia y descartar duplicados.
  • Orden de llegada: el orden de recepción no está estrictamente garantizado. Utiliza la marca temporal created_at y, en credits.updated, la secuencia monótona credit_sequence para descartar actualizaciones obsoletas.

Supervisa y corrige las entregas

Cada endpoint muestra sus Entregas recientes: En cola, Enviando, Entregado, Reintentando o Fallido, con el número de intento, el último estado HTTP y la hora del siguiente intento.

Las entregas fallidas no se vuelven a enviar. Después de una caída, concilia los datos con la API, por ejemplo con GET /generations o GET /credits/history.

Desde el endpoint también puedes:

  • Editar eventos para cambiar lo que recibe;
  • Rotar secreto para sustituir el secreto de firma: a partir de ese momento las entregas se firman con el nuevo, así que actualiza antes tu servidor;
  • Eliminar el endpoint, lo que detiene las entregas y borra su historial.