Webhooks

A workspace's endpoints receive a signed event when a batch ends, in OpenAI's webhook format, so OpenAI's webhook verifiers work. Endpoints are set up in the Console, with the events each receives and a signing secret shown once. No endpoint, no webhook: polling the batch always works. The events come only from batches, which are not offered in production yet; the endpoint tools in the Console are live.

00000000000000000000000000000000000000001{"object": "event", "id": "evt_...", "type": "batch.completed", "created_at": 1792663200, "data": {"id": "batch_..."}}

The payload names the batch; read the batch for its state. One event per batch, emitted when it enters that terminal status.

00000000000000000000000000000000000000001import base64, hashlib, hmac, time2 3def verified(signing_secret: str, headers: dict, body: bytes, tolerance_s: int) -> bool:4    # signing_secret: the endpoint's secret from the Console, whsec_ and base64.5    secret = base64.b64decode(signing_secret.removeprefix("whsec_"))6    msg_id = headers["webhook-id"]7    timestamp = headers["webhook-timestamp"]8    if abs(time.time() - int(timestamp)) > tolerance_s:9        return False10    signed = f"{msg_id}.{timestamp}.".encode() + body11    expected = base64.b64encode(hmac.new(secret, signed, hashlib.sha256).digest()).decode()12    return any(13        part.startswith("v1,") and hmac.compare_digest(part[3:], expected)14        for part in headers["webhook-signature"].split(" ")15    )

• A POST with Content-Type: application/json. A 2xx within the delivery timeout Not decided yet delivers; anything else, a redirect included (never followed), is retried with exponential backoff and jitter for up to a retry window Not decided yet, then recorded as failed in the endpoint's delivery log.
• At least once; the order of deliveries is not guaranteed. Order by the payload's created_at only to the second, and read the batch when the order matters.
• An endpoint that keeps failing is never switched off: it is probed until its first success.
• The sender refuses any host that resolves to a private, loopback, link-local or metadata address.

• Add an endpoint: an https URL on a public host and the events it receives; the signing secret is shown once.
• Send a test: webhook.test, or a sample of one of the endpoint's events, marked as a test and naming no batch.
• Rotate the secret: the retired secret keeps signing beside the new one for an overlap, which you may end sooner.
• The deliveries log, each with its attempts; redeliver one, redeliver the failed deliveries of a period after an outage, or recover an endpoint that backs off once its receiver is fixed.