Test OpenAI Webhooks Locally

From a stuck handler to a live OpenAI delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 3000. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL, something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3Open the webhook settings page at Dashboard → Settings → Project → Webhooks (platform.openai.com/settings/project/webhooks). Webhooks are configured per project, so check the project selector first. Create an endpoint, paste your LocalCan URL with your route, e.g. https://your-app-12.localcan.dev/webhooks/openai, and subscribe to the event types you want. OpenAI then shows the signing secret (whsec_…). Copy it into OPENAI_WEBHOOK_SECRET before you leave the page, because in OpenAI’s words you “won’t be able to view it again”.
4. 4From that same settings page, trigger a test event with sample data. It is the only on-demand event OpenAI gives you: there is no openai webhooks trigger, and a real one arrives when the work finishes. A Batch job can take up to 24 hours.
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body. Expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

Header

webhook-signature

Algorithm

HMAC-SHA256, base64-encoded (space-delimited v1,<sig> list)

What's signed

OpenAI signs the string {webhook-id}.{webhook-timestamp}.{raw body}: the webhook-id header, a literal dot, the webhook-timestamp header, a literal dot, then the exact bytes of the body. The HMAC-SHA256 key is not the whsec_ string: strip the whsec_ prefix and base64-decode the rest for the key bytes. The digest is base64-encoded and compared against each space-separated entry in webhook-signature once its v1, prefix is removed. Several entries appear while a secret is rotating, and any may match.

Secret

The endpoint signing secret (whsec_…), issued when you create the endpoint at platform.openai.com/settings/project/webhooks and shown once. The SDKs read it from OPENAI_WEBHOOK_SECRET. It is scoped to that endpoint in that project, so a secret that looks right but never matches is usually the right secret for the wrong project. Lose it and the only route back is rotating it from the same page.

import express from 'express'
import OpenAI from 'openai'

const client = new OpenAI() // reads OPENAI_API_KEY
const webhookSecret = process.env.OPENAI_WEBHOOK_SECRET // whsec_...

const app = express()

// OpenAI signs the RAW bytes. Mount express.raw on this route only. A global
// express.json() hands unwrap() a parsed object and every signature fails.
app.post('/webhooks/openai', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    // unwrap() recomputes HMAC-SHA256 over "{webhook-id}.{webhook-timestamp}.{body}",
    // checks webhook-timestamp against a tolerance, then JSON.parses the payload.
    // The 4th argument is that tolerance in seconds and defaults to 300. Widen it
    // in dev to replay an older capture:
    //   client.webhooks.unwrap(body, req.headers, webhookSecret, 86400)
    const event = await client.webhooks.unwrap(
      req.body.toString('utf8'),
      req.headers,
      webhookSecret,
    )

    if (event.type === 'response.completed') {
      // event.data.id is the Response id. Fetch the result AFTER responding.
    }

    // Acknowledge first, work later: anything that is not a 2xx "within a few
    // seconds" is retried with backoff for up to 72 hours.
    res.status(200).send('ok')
  } catch (err) {
    // InvalidWebhookSignatureError: parsed body, wrong secret, or stale timestamp.
    res.status(400).send('Invalid signature: ' + err.message)
  }
})

app.listen(3000)

Not by default, and OpenAI hands you the fix. webhook-timestamp is signed into the digest and unwrap() rejects anything more than 300 seconds old with Webhook timestamp is too old, so a capture from five minutes ago verifies and one from this morning does not. The fourth argument to unwrap() is that tolerance in seconds. Pass 86400 behind a dev-only flag and yesterday’s captured batch.completed replays exactly as it arrived. Keep the default in production, where the window is the replay-attack defence.