Os webhooks da OpenAI permitem receber notificações em tempo real sobre eventos na API, como quando um lote é concluído, uma resposta em segundo plano é gerada ou um trabalho de ajuste fino é finalizado. Os webhooks são entregues a um endpoint HTTP que você controla, seguindo a especificação Standard Webhooks. A lista completa de eventos de webhook está disponível na referência da API.
Para receber notificações de monitoramento de desalinhamento de um projeto de API, consulte Receber alertas de segurança do projeto.
Para sessões da API de Agentes, consulte Webhooks de sessão para obter informações sobre eventos de sessão e padrões de recuperação. Para o receptor de webhooks, siga as orientações desta página sobre configuração do endpoint, verificação de assinatura e entrega.
Veja a lista completa de eventos de webhook.
Veja abaixo exemplos de servidores capazes de receber webhooks da OpenAI, especificamente para o evento response.completed.
Para os exemplos em Ruby, instale as dependências necessárias com
gem install openai webrick e, em seguida, defina OPENAI_API_KEY e
OPENAI_WEBHOOK_SECRET.
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 um webhook como esse em ação, você pode configurar um endpoint de webhook no painel da OpenAI inscrito em response.completed e, em seguida, fazer uma requisição à API para gerar uma resposta no modo em segundo plano.
Você também pode disparar eventos de teste com dados de exemplo na página de configurações de webhooks.
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)Neste guia, você aprenderá a criar endpoints de webhook no painel, configurar o código do servidor para lidar com eles e verificar se as requisições recebidas vieram da OpenAI.
Como criar endpoints de webhook
Para começar a receber requisições de webhook no seu servidor, entre no painel e abra a página de configurações de webhooks. Os webhooks são configurados por projeto.
Clique no botão "Criar" para criar um novo endpoint de webhook. Você configurará três itens:
- Um nome para o endpoint (apenas para sua referência).
- Uma URL pública de um servidor que você controla.
- Um ou mais tipos de evento nos quais se inscrever. Quando eles ocorrerem, a OpenAI enviará uma requisição HTTP POST para a URL especificada.
Depois de criar um webhook, você receberá uma chave secreta de assinatura para verificar, no servidor, as requisições de webhook recebidas. Guarde esse valor para usar depois, pois você não poderá visualizá-lo novamente.
Com o endpoint de webhook criado, o próximo passo é configurar um endpoint no servidor para processar os payloads dos eventos recebidos.
Como processar requisições de webhook em um servidor
Quando ocorrer um evento no qual você se inscreveu, a URL do seu webhook receberá uma requisição 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" }
}
Seu endpoint deve responder rapidamente a essas requisições HTTP recebidas com um código de status de sucesso (2xx), confirmando o recebimento. Para evitar que o tempo limite seja excedido, recomendamos delegar qualquer processamento não trivial a um processo de trabalho em segundo plano, para que o endpoint possa responder imediatamente.
Se o endpoint não retornar um código de status de sucesso (2xx) ou não responder em poucos segundos, a requisição de webhook será reenviada. A OpenAI continuará tentando realizar a entrega por até 72 horas, com intervalos que aumentam exponencialmente. Observe que os redirecionamentos 3xx não serão seguidos; eles são tratados como falhas, e seu endpoint deve ser atualizado para usar a URL de destino final.
Em casos raros, devido a problemas internos do sistema, a OpenAI pode entregar cópias duplicadas do mesmo evento de webhook. Você pode usar o cabeçalho webhook-id como chave de idempotência para eliminar duplicatas.
Como testar webhooks localmente
Para testar webhooks, é necessária uma URL acessível pela internet pública. Isso pode dificultar o desenvolvimento, já que seu ambiente de desenvolvimento local provavelmente não está aberto ao público. Algumas opções que podem ajudar:
- ngrok, que pode disponibilizar seu servidor localhost em uma URL pública
- Ambientes de desenvolvimento em nuvem, como Replit, GitHub Codespaces, Cloudflare Workers ou v0 da Vercel.
Como verificar assinaturas de webhooks
Embora seja possível receber eventos de webhook da OpenAI e processar os resultados sem nenhuma verificação, você deve verificar se as requisições recebidas vêm da OpenAI, especialmente se seu webhook executar qualquer tipo de ação no backend. Os cabeçalhos enviados com as requisições de webhook contêm informações que podem ser usadas em conjunto com uma chave secreta de webhook para verificar se ele se originou na OpenAI.
Ao criar um endpoint de webhook no painel da OpenAI, você receberá uma chave secreta de assinatura que deverá disponibilizar no seu servidor como uma variável de ambiente:
export OPENAI_WEBHOOK_SECRET="<your secret here>"
A maneira mais simples de verificar assinaturas de webhooks é usar o método unwrap() dos utilitários oficiais do OpenAI SDK:
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,
)As assinaturas também podem ser verificadas com as bibliotecas Standard Webhooks:
$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);Se necessário, você também pode implementar sua própria verificação de assinaturas conforme descrito na especificação Standard Webhooks
Se você perder ou expuser acidentalmente sua chave secreta de assinatura, poderá gerar uma nova fazendo a rotação da chave secreta de assinatura.