OpenAI Webhooks: Events, Signature Headers and unwrap() in Node and Python

Does OpenAI support webhooks?

Which OpenAI events trigger a webhook?

You choose event types per endpoint. These are the job events from the webhook events reference (as of September 2026); a few account-level notices, such as safety warnings, are listed there too.

How do webhooks work with Responses API background mode?

Create the response with background=True; when it finishes, OpenAI sends a response.* event to every project endpoint subscribed to it. The call returns right away with status queued. Keep the response ID so you can match the webhook to your own record.

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="your-model",          # any model that supports background mode
    input="Research the 2026 EU AI Act obligations for SaaS vendors.",
    background=True,             # returns immediately with status "queued"
)
print(resp.id, resp.status)      # store resp.id; the webhook will reference it

The webhook body is intentionally thin. It tells you what happened and to which object, not the output itself:

{
  "object": "event",
  "id": "evt_685343a1381c819085d44c354e1b330e",
  "type": "response.completed",
  "created_at": 1750287018,
  "data": { "id": "resp_abc123" }
}

Fetch the output with client.responses.retrieve(event.data.id). The same pattern applies to batch.* (retrieve the batch, then its output_file_id), fine-tuning jobs and eval runs. Deep research models run through this same background flow; there is no separate deep research webhook.

How do I set up an OpenAI webhook endpoint?

1. In the OpenAI dashboard, open the project that makes the async calls and go to Settings → Project → Webhooks (platform.openai.com/settings/project/webhooks).
2. Create an endpoint with a public HTTPS URL.
3. Select the event types you want delivered, for example response.completed and batch.completed.
4. Copy the signing secret right away (OpenAI won't show it again) and store it as OPENAI_WEBHOOK_SECRET in your secrets manager. Both SDKs read that variable automatically.
5. Use the settings page to send a test event with sample data and confirm your endpoint answers with a 2xx.

Endpoints are per project. If the API key that starts a job belongs to another project, that project's endpoints receive the event.

What headers does an OpenAI webhook include?

OpenAI signs every delivery with the three Standard Webhooks headers: webhook-id, webhook-timestamp and webhook-signature. If you were looking for an openai-signature or x-openai-signature header, it doesn't exist.

POST /openai/webhook HTTP/1.1
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=

• webhook-id: unique per event and, per the Standard Webhooks spec, the same when a delivery is retried. Use it as your idempotency key.
• webhook-timestamp: Unix seconds. The SDKs reject anything more than 300 seconds old or ahead.
• webhook-signature: v1, followed by a base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}. During secret rotation it can hold several space-separated signatures; accept any match.

How do I verify OpenAI webhooks with unwrap()?

Pass the raw request body and the headers to client.webhooks.unwrap(); it verifies the signature and timestamp, then returns the parsed, typed event. It raises InvalidWebhookSignatureError on a bad or stale signature. If you only want the check, verify_signature() (verifySignature() in Node) does that and takes an optional tolerance in seconds.

Python (Flask)

import os
from flask import Flask, request
from openai import OpenAI, InvalidWebhookSignatureError

app = Flask(__name__)
client = OpenAI()  # reads OPENAI_API_KEY and OPENAI_WEBHOOK_SECRET

@app.post("/openai/webhook")
def openai_webhook():
    try:
        # request.data is the raw body; unwrap checks webhook-id,
        # webhook-timestamp and webhook-signature, then parses the event
        event = client.webhooks.unwrap(request.data, request.headers)
    except InvalidWebhookSignatureError:
        return "invalid signature", 400

    if already_processed(request.headers["webhook-id"]):
        return "", 200

    if event.type == "response.completed":
        response = client.responses.retrieve(event.data.id)
        save_output(event.data.id, response.output_text)
    elif event.type in ("response.failed", "response.incomplete", "response.cancelled"):
        mark_unfinished(event.data.id, event.type)
    elif event.type == "batch.completed":
        batch = client.batches.retrieve(event.data.id)
        enqueue_download(batch.output_file_id)

    return "", 200

Node.js (Express)

Two details break most Node handlers: unwrap() returns a Promise, and it expects the body as a string. If express.json() has already parsed it, the signature can't match.

import express from "express";
import OpenAI, { InvalidWebhookSignatureError } from "openai";

const app = express();
const client = new OpenAI(); // reads OPENAI_API_KEY and OPENAI_WEBHOOK_SECRET

// unwrap() needs the raw body as a string, so don't use express.json() here
app.post("/openai/webhook", express.text({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = await client.webhooks.unwrap(req.body, req.headers); // async in Node
  } catch (err) {
    if (err instanceof InvalidWebhookSignatureError) {
      return res.status(400).send("invalid signature");
    }
    throw err;
  }

  res.sendStatus(200); // acknowledge within a few seconds, then do the work

  if (event.type === "response.completed") {
    const response = await client.responses.retrieve(event.data.id);
    await saveOutput(event.data.id, response.output_text);
  }
});

Without the SDK

Any Standard Webhooks library (for example the standardwebhooks package) works too. This is the same check by hand:

import crypto from "node:crypto";

// Standard Webhooks verification without the OpenAI SDK
export function verifyOpenAIWebhook(rawBody: string, headers: Record<string, string>, secret: string) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = (headers["webhook-signature"] ?? "").split(" "); // may hold several during rotation

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = secret.startsWith("whsec_")
    ? Buffer.from(secret.slice("whsec_".length), "base64")
    : Buffer.from(secret, "utf8");
  const expected = crypto
    .createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();

  return signatures.some((sig) => {
    const candidate = Buffer.from(sig.replace(/^v1,/, ""), "base64");
    return candidate.length === expected.length && crypto.timingSafeEqual(candidate, expected);
  });
}

How do I test OpenAI webhooks locally?

Give OpenAI a public HTTPS URL that forwards to your machine, then start a real background job. OpenAI can't reach localhost, so you need a tunnel or a hosted capture URL. With the Hooklistener CLI:

npm i -g hooklistener        # or: brew tap hooklistener/tap && brew install hooklistener
hooklistener login
hooklistener tunnel --port 5000   # prints a public HTTPS URL for localhost:5000

Register that URL plus your path (for example /openai/webhook) in the project's webhook settings. ngrok and other localhost tunnels work the same way.

One catch when replaying a captured event later: the SDK rejects it as "Webhook timestamp is too old" after 5 minutes, because the signature covers the original timestamp. In development only, verify with a wider window, for example client.webhooks.verify_signature(body, headers, tolerance=86400), then parse the body yourself.

How should I handle retries and duplicates?

Respond with a 2xx within a few seconds and dedupe on webhook-id. If your endpoint times out or returns a non-2xx status, OpenAI retries with exponential backoff for up to 72 hours, so the same event can arrive more than once. Don't rely on delivery order either; re-read the object's current status when it matters.

# Return 2xx quickly for anything you accepted (even if you queue the work).
# Return 400 for bad signatures: retrying will never fix them.
# Return 5xx only for transient failures you want OpenAI to retry (up to 72 h).

seen = redis.set(f"openai:webhook:{webhook_id}", 1, nx=True, ex=4 * 24 * 3600)
if not seen:
    return "", 200  # duplicate delivery, already handled

Why is my OpenAI webhook failing?

• -
  Signature never matches: the body was parsed or re-serialized before verification, or the secret belongs to another project or endpoint. Verify the raw bytes with the secret of the endpoint that received the event.
• -
  "Webhook timestamp is too old": server clock drift, or you are replaying an old delivery. Sync the clock with NTP; widen the tolerance only in development.
• -
  No events arrive: the job wasn't started in background mode, the endpoint isn't subscribed to that event type, or the job ran under a different project's API key.
• -
  event.data has no output: expected. Webhook events only carry the object ID; retrieve the object for its content.

FAQ

Related Resources