For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal

Webhooks

Usa webhooks para recibir actualizaciones en tiempo real de la API de OpenAI.

Los webhooks de OpenAI te permiten recibir notificaciones en tiempo real sobre eventos de la API, como cuando se completa un lote, se genera una respuesta en segundo plano o finaliza un trabajo de ajuste fino. Los webhooks se entregan a un punto de acceso HTTP bajo tu control, de acuerdo con la especificación Standard Webhooks. Puedes encontrar la lista completa de eventos de webhook en la referencia de la API.

Para recibir notificaciones de monitoreo de desalineación de un proyecto de la API, consulta Recibir alertas de seguridad del proyecto.

Para las sesiones de la API de agentes, consulta Webhooks de sesión para obtener información sobre los eventos de sesión y los patrones de recuperación. Para el receptor de webhooks, sigue las indicaciones de esta página sobre la configuración del punto de acceso, la verificación de firmas y la entrega.

Referencia de la API para eventos de webhook

Consulta la lista completa de eventos de webhook.

A continuación se muestran ejemplos de servidores capaces de recibir webhooks de OpenAI, específicamente para el evento response.completed.

Para los ejemplos de Ruby, instala las dependencias necesarias con gem install openai webrick y luego configura OPENAI_API_KEY y OPENAI_WEBHOOK_SECRET.

Servidor de webhooks
import os
from openai import OpenAI, InvalidWebhookSignatureError
from flask import Flask, request, Response

app = Flask(__name__)
client = OpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])


@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        # with webhook_secret set above, unwrap will raise an error if the signature is invalid
        event = client.webhooks.unwrap(request.data, request.headers)

        if event.type == "response.completed":
            response_id = event.data.id
            response = client.responses.retrieve(response_id)
            print("Response output:", response.output_text)

        return Response(status=200)
    except InvalidWebhookSignatureError as e:
        print("Invalid signature", e)
        return Response("Invalid signature", status=400)


if __name__ == "__main__":
    app.run(port=8000)

Para ver un webhook como este en acción, puedes configurar un punto de acceso de webhook en el panel de OpenAI suscrito a response.completed y luego realizar una solicitud a la API para generar una respuesta en modo en segundo plano.

También puedes activar eventos de prueba con datos de ejemplo desde la página de configuración de webhooks.

Generar una respuesta en segundo plano
from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    input="Write a very long novel about otters in space.",
    background=True,
)

print(resp.status)

En esta guía, aprenderás a crear puntos de acceso de webhook en el panel, configurar código del lado del servidor para procesarlos y verificar que las solicitudes entrantes provengan de OpenAI.

Crear puntos de acceso de webhook

Para empezar a recibir solicitudes de webhook en tu servidor, inicia sesión en el panel y abre la página de configuración de webhooks. Los webhooks se configuran por proyecto.

Haz clic en el botón “Crear” para crear un nuevo punto de acceso de webhook. Configurarás tres cosas:

  • Un nombre para el punto de acceso (solo como referencia para ti).
  • Una URL pública de un servidor bajo tu control.
  • Uno o más tipos de eventos a los que suscribirte. Cuando ocurran, OpenAI enviará una solicitud HTTP POST a la URL especificada.
cuadro de diálogo para editar un punto de acceso de webhook

Después de crear un nuevo webhook, recibirás un secreto de firma para verificar las solicitudes de webhook entrantes del lado del servidor. Guarda este valor para usarlo más adelante, ya que no podrás volver a verlo.

Una vez creado el punto de acceso de webhook, configurarás un punto de acceso del lado del servidor para procesar los datos de esos eventos entrantes.

Procesar solicitudes de webhook en un servidor

Cuando ocurra un evento al que te hayas suscrito, la URL de tu webhook recibirá una solicitud HTTP POST como esta:

POST https://yourserver.com/webhook
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52
webhook-timestamp: 1750287078
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{
  "object": "event",
  "id": "evt_685343a1381c819085d44c354e1b330e",
  "type": "response.completed",
  "created_at": 1750287018,
  "data": { "id": "resp_abc123" }
}

Tu punto de acceso debe responder rápidamente a estas solicitudes HTTP entrantes con un código de estado de éxito (2xx) que indique que se recibieron correctamente. Para evitar que se agote el tiempo de espera, recomendamos delegar cualquier procesamiento que no sea trivial a un proceso de trabajo en segundo plano, de modo que el punto de acceso pueda responder de inmediato. Si el punto de acceso no devuelve un código de estado de éxito (2xx) o no responde en unos segundos, se volverá a intentar la solicitud de webhook. OpenAI seguirá intentando la entrega durante un máximo de 72 horas, con tiempos de espera que aumentan de forma exponencial. Ten en cuenta que no se seguirán las redirecciones 3xx; se consideran fallas y debes actualizar tu punto de acceso para usar la URL de destino final.

En casos excepcionales, debido a problemas internos del sistema, OpenAI puede entregar copias duplicadas del mismo evento de webhook. Puedes usar el encabezado webhook-id como clave de idempotencia para eliminar duplicados.

Probar webhooks localmente

Para probar webhooks se necesita una URL accesible desde la Internet pública. Esto puede complicar el desarrollo, ya que es probable que tu entorno de desarrollo local no sea accesible al público. Estas son algunas opciones que pueden ayudar:

Verificar firmas de webhooks

Aunque puedes recibir eventos de webhook de OpenAI y procesar los resultados sin verificarlos, debes comprobar que las solicitudes entrantes provengan de OpenAI, especialmente si tu webhook realizará algún tipo de acción en el backend. Los encabezados enviados junto con las solicitudes de webhook contienen información que puede usarse en combinación con una clave secreta de webhook para verificar que el webhook provenga de OpenAI.

Cuando crees un punto de acceso de webhook en el panel de OpenAI, recibirás un secreto de firma que debes poner a disposición en tu servidor como variable de entorno:

export OPENAI_WEBHOOK_SECRET="<your secret here>"

La forma más sencilla de verificar las firmas de webhooks es usar el método unwrap() de las utilidades del SDK oficial de OpenAI:

Verificación de firmas con el SDK de OpenAI
import os

from flask import request
from openai import OpenAI

client = OpenAI()
webhook_secret = os.environ["OPENAI_WEBHOOK_SECRET"]

# will raise if the signature is invalid
event = client.webhooks.unwrap(
    request.data,
    request.headers,
    secret=webhook_secret,
)

También puedes verificar las firmas con las bibliotecas de Standard Webhooks:

Verificación de firmas con las bibliotecas de Standard Webhooks
$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);

Como alternativa, si lo necesitas, puedes implementar tu propia verificación de firmas según se describe en la especificación Standard Webhooks

Si pierdes tu secreto de firma o lo expones por accidente, puedes generar uno nuevo mediante la rotación del secreto de firma.