A small museum wants to classify several hundred digitized object descriptions. Its API sends an event after a background tagging response finishes, and a worker prepares suggestions for curatorial review. The risk is subtle: receiving the same event twice could insert the same suggestion twice, while treating a delivered notification as approval could change the public catalog without anyone checking the original scan. OpenAI webhooks provide notifications, not a publishing decision.
This tutorial outlines a hypothetical receiver design. It does not report a deployed server, real tagging accuracy, or a tested production connection. The objective is to separate event authenticity, event delivery, API response state, and archival approval into independently verifiable steps.
Understand what the webhook actually tells you
The OpenAI Webhooks guide documents notifications for events such as `response.completed`, and it shows a payload containing an event ID, event type, and a response ID in the data object. The notification is not itself the finished museum metadata. It tells an application that a relevant event occurred and provides an identifier for retrieving or reconciling the corresponding response.
Define three statuses in your own workflow: delivery received, generated output retrieved, and catalog entry approved. Do not call all three “complete.” For example, a tagging response may be complete but contain an unsupported attribution to a particular maker. That answer belongs in a reviewer queue, not in the authoritative catalog, even when the webhook arrived with a valid signature.
Register a narrow endpoint and protect its secret
In the API dashboard, configure a project webhook endpoint with an HTTPS URL under your control and subscribe only to event types you need. OpenAI supplies a signing secret when the endpoint is created. Keep it server-side in a secret manager or protected environment variable; do not paste it into frontend JavaScript, logs, article examples, or a public repository.
Restrict what the receiver is allowed to do. Its first job is to authenticate the request and put a tiny, durable event record into a queue. The event endpoint should not be able to publish catalog pages or change an accession record merely because it received a JSON payload. This narrows the impact of a mistake in parsing or validation.
Verify the raw request before trusting its contents
OpenAI documents verifying webhook signatures with the official SDK’s `webhooks.unwrap` helper, using the original request body and received headers. Verification is important because any internet-facing endpoint may receive forged POST requests. Parse and act on the event only after the verification step succeeds; reject invalid signatures and malformed requests without writing a catalog update.
Retain only necessary diagnostics such as an internal receipt timestamp, event type, verification outcome, and correlation identifier. Avoid logging signing secrets or full descriptions containing donor details. If signature validation fails, record a safe error code, investigate the endpoint configuration, and do not retry the failed payload as if it were a trustworthy event.
Deduplicate delivery with an event identifier
Webhooks are delivered with retry behavior. OpenAI says unsuccessful or slow responses can trigger redelivery, and rare duplicate deliveries can occur. Its guide recommends the `webhook-id` header as an idempotency key. Save that value in a database column with a uniqueness constraint before enqueueing work. If a duplicate arrives, return an appropriate success acknowledgement for the already accepted delivery rather than enqueueing another catalog change.
A webhook ID is not interchangeable with a response ID. One identifies a particular delivery event; the other identifies an API response your worker may need to retrieve. Track both. The illustrative comparison graphic contrasts a flawed receiver that makes two tagging rows from one retried event with a corrected design that records one event and creates one human-review item.
Acknowledge quickly and process later
OpenAI recommends returning a successful 2xx response promptly and moving nontrivial work into a background worker. A slow receiver that tries to fetch PDFs, compare taxonomies, and render thumbnails before responding may encourage retries. Write the minimal verified receipt transaction first, then acknowledge. Give the worker its own retry and monitoring logic.
Make worker operations idempotent too: the uniqueness constraint on incoming events will not protect against a worker crashing after creating a review task but before marking itself finished. Associate the task with a stable response ID and source revision. On restart, inspect that record before opening a replacement task. A “completed” indicator should mean exactly the stage its column names.
Retrieve the response and preserve evidence
For a `response.completed` notification, obtain the corresponding response through the documented API and inspect what was actually returned. Store candidate tag suggestions alongside the accession number, source image or transcription revision, and any supporting quotation the model supplied. Neither a successful network request nor a confident noun proves the subject has been identified correctly.
Suppose an old apparatus is labeled “surveying instrument” by a classifier. The original inventory may say only “brass measurement device.” Mark the specific suggestion unresolved until a curator checks evidence. This is especially important if a model invents a maker or century that cannot be verified from the physical object, accession book, or permitted reference material.
Audit failure modes without inventing performance numbers
Build local test fixtures for a forged signature, duplicated event ID, queue timeout, unknown response ID, worker restart, stale transcription, and a reviewer rejecting a plausible label. These are proposed tests, not measurements performed for this article. Confirm that every case reaches a known state and that none of them silently changes the public catalog.
Review sensitive-data paths too. An event record should not become an unrestricted copy of private intake correspondence. Separate diagnostic retention from archive retention, check who can read worker logs, and rotate credentials using the documented controls if an endpoint secret is exposed. A rejected event is never a substitute for staff reviewing a genuine source document.
Publish only a signed-off catalog revision
A curator should accept, edit, or reject each candidate field while viewing the original record. Save the approval identity, decision timestamp, taxonomy version, and exact source revision. Then allow the application’s normal publication workflow to apply the reviewed change. If the scan changes later, the old review may no longer justify the same tag.
The meaningful success criterion is a faithful record of how a tag reached approval, not a flashy notification feed. Verified deliveries, deduplicated work, and explicit curatorial decisions make the pipeline reliable even when network delivery is imperfect. Webhooks automate notification; responsibility for the museum’s factual record stays with the museum.
How We Research
For this November 2026 editorial review, we read the named official materials: OpenAI API Webhooks guide, OpenAI Responses API background mode. We compared the documented user actions, feature restrictions, supported source types, and security or data limitations against the illustrative scenario. We did not access a live account, run a controlled experiment, measure vendor accuracy, inspect real contracts, or verify fictional artwork as a product screenshot. Interface labels, eligibility, availability, and pricing may change; revisit the cited documentation and get the appropriate local authorization before deployment.
Frequently Asked Questions
No. It reports a response event, not a museum editorial decision. Retrieve the output and require the normal source-review step.
Unsuccessful or slow delivery can lead to retries, and duplicate delivery is possible. Use the documented webhook-id as an idempotency key.
No. Store it server-side and verify each request with the documented SDK helper or Standard Webhooks mechanism.
Prefer a short verified receipt and a durable worker queue. OpenAI advises returning 2xx promptly to reduce unnecessary retries.
No. The event ID identifies the notification, while the response ID identifies the API response for retrieval and reconciliation.