Webhooks

01Preparación

1. Consigue el secreto de firma

   En el portal, en la sección «Webhooks», copia el secreto de firma de la cuenta. Empieza por whsec_ y es uno solo para todas tus claves de API. El secreto debe existir en el momento en que la tarea termine. No es una clave de API: los valores son distintos.

2. Prepara la dirección

   Hace falta una dirección HTTPS accesible desde internet, con un certificado válido. No sirven localhost, las direcciones de redes internas ni otros destinos prohibidos. La longitud de la dirección es de hasta 2 048 caracteres. En la entrega no se siguen las redirecciones, así que indica la dirección final.

3. Añade webhook_url a la solicitud

   Indica la dirección en cada solicitud de generación para la que quieras recibir una notificación. Una dirección incorrecta o prohibida devuelve 400 antes del cargo.

   POST /images/generateCopiar

   {
     "model": "nano-banana-pro",
     "prompt": "Taza de cerámica sobre mármol",
     "webhook_url": "https://example.com/webhooks/rendergrid"
   }

02Qué llega a tu dirección

03Eventos

El cuerpo del evento es un JSON con los campos event, id, status, result_urls y cost. El evento de error añade error y failure.

{
  "event": "creation.completed",
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "completed",
  "result_urls": [
    "https://cdn.rendergrid.io/images/example/result.jpg"
  ],
  "cost": 0.04
}

{
  "event": "creation.failed",
  "id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
  "status": "failed",
  "result_urls": [],
  "cost": 0.04,
  "error": "Generation failed.",
  "failure": {
    "type": "error",
    "code": "internal",
    "retryable": true
  }
}

{
  "event": "creation.completed",
  "id": "test",
  "test": true
}

cost

El cargo original en dólares estadounidenses (USD). No es una confirmación de reembolso ni el saldo. Si no hay importe, llega null.

error

Un texto para mostrar o null. El éxito o el fallo se determinan por status, no por el texto.

failure

La causa del fallo para el programa: type, code, retryable. Qué significan.

result_urls

Enlaces a los archivos. En un evento fallido la lista está vacía. Los archivos duran un día: descárgalos enseguida.

04Verificación de la firma

La firma sirve para comprobar que el mensaje viene de nosotros y que nadie lo ha modificado. Se calcula así:

1. Toma los bytes originales del cuerpo, antes de que el framework analice el JSON.
2. Concatena el valor de X-Timestamp, un punto y el cuerpo.
3. Calcula el HMAC-SHA256 de esa cadena. La clave es el secreto completo, con whsec_, en bytes UTF-8.
4. Compara sha256= y el resultado con el encabezado X-Webhook-Signature-256 en tiempo constante.
5. Rechaza la solicitud si la marca de tiempo queda fuera de la ventana. En los ejemplos la ventana es de 300 segundos; es una regla del receptor, no un plazo de reentrega.

import hashlib
import hmac
import re
import time

TOLERANCE_SECONDS = 300


def verify_webhook(
    secret: str, timestamp: str, raw_body: bytes, signature: str
) -> bool:
    if not isinstance(secret, str) or not secret:
        return False
    if not isinstance(raw_body, bytes):
        return False
    if not re.fullmatch(r"[0-9]{1,12}", timestamp or ""):
        return False
    if not re.fullmatch(r"sha256=[0-9a-f]{64}", signature or ""):
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        timestamp.encode("ascii") + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;
const TS_RE = /^[0-9]{1,12}$/;
const SIG_RE = /^sha256=[0-9a-f]{64}$/;

export function verifyWebhook(secret, timestamp, rawBody, signature) {
  if (typeof secret !== "string" || !secret) return false;
  if (!Buffer.isBuffer(rawBody)) return false;
  if (typeof timestamp !== "string" || !TS_RE.test(timestamp)) {
    return false;
  }
  if (typeof signature !== "string" || !SIG_RE.test(signature)) {
    return false;
  }
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > TOLERANCE_SECONDS) return false;
  const expected =
    "sha256=" +
    createHmac("sha256", Buffer.from(secret, "utf8"))
      .update(timestamp + ".", "ascii")
      .update(rawBody)
      .digest("hex");
  return timingSafeEqual(Buffer.from(expected, "ascii"), Buffer.from(signature, "ascii"));
}

Analiza el JSON y ejecuta acciones solo después de una comprobación correcta.

05Compruébalo con un ejemplo

Tres solicitudes ya preparadas y firmadas de verdad. Elige una y pulsa el botón.

06Confirmación y reintentos

Cualquier respuesta 2xx significa «recibido». Las demás respuestas y los errores de red los consideramos un fallo y repetimos la entrega: por defecto, hasta cinco intentos en total.

• Esperamos la respuesta 10 segundos. Confirma la recepción rápido y deja para después la descarga de imágenes y el trabajo largo.
• Primero guarda el evento de forma fiable o ponlo en una cola, y después responde 2xx. Si no has podido aceptarlo, responde con otro estado.
• Ejecuta la acción una sola vez por cada pareja (id, event). X-Webhook-Delivery-ID ayuda a eliminar duplicados. Una repetición debe ser segura incluso si tu confirmación se perdió.
• Un error de entrega no pasa la tarea a failed. El estado siempre se puede consultar en GET /creations/{id}, y el historial de entregas, en el portal.

07El secreto de firma y su sustitución

Todas las claves de API de la cuenta firman los webhooks con un mismo secreto. Guárdalo en el servidor, en un almacén de secretos.

Tras la sustitución en el portal, el secreto nuevo pasa a ser el actual al instante: con él se firman todos los intentos siguientes, incluidas las repeticiones. Actualiza el controlador de inmediato y durante 24 horas más acepta también el secreto anterior, sin dejar de comprobar la frescura de la marca de tiempo. Solo se conserva un secreto anterior: la siguiente sustitución lo desplazará.

08Envío de prueba

En el portal puedes enviar una prueba firmada a una dirección HTTPS permitida. Como máximo una vez cada 30 segundos por cuenta; la prueba sale una sola vez, sin reintentos. El cuerpo es más corto que el de un evento real:

{
  "event": "creation.completed",
  "id": "test",
  "test": true
}

Comprueba la firma, verifica que llega test: true, responde 2xx y no proceses el resultado. La prueba no lleva status, result_urls ni cost: no los exijas. El registro de las últimas entregas y de sus resultados está ahí mismo, en el portal, con las más recientes arriba.

FAQPreguntas frecuentes