Automated Excellence
Build event-driven workflows that react to Codex events in real time. Subscribe to generation completions, review results, project changes, and team activity — with signed payloads and automatic retries.
Subscribe to generation, review, project, and team events. Filter by event type, project, and severity to receive only the signals you care about.
Every payload is signed with your secret. Verify the X-Codex-Signature header against the raw request body to confirm authenticity.
Five retries with exponential backoff: 1 min, 5 min, 25 min, 2 hr, 6 hr. Your endpoint gets every event — even through transient downtime.
View 30 days of delivery history — HTTP status, response body, and retry timeline — from the Codex dashboard or API.
Webhooks are HTTP callbacks. When something happens in Codex that you care about, Codex POSTs a JSON payload to a URL you provide. Your server receives it and acts — in real time, without polling.
The webhook architecture follows a pattern familiar to anyone who has integrated with GitHub, Stripe, or Slack webhooks. You register an endpoint URL in the Codex dashboard or via the API. You select which event types to subscribe to. Optionally, you provide a secret string that Codex uses to sign every payload. When a subscribed event fires — a code review completes, a team member is added, a project is indexed — Codex constructs a JSON payload, signs it with your secret, and POSTs it to your URL. Your server validates the signature, parses the JSON, and executes whatever logic you have defined: posting a Slack message, triggering a deployment, updating a database, enqueuing a background job. The entire round trip from event occurrence to your server receiving the payload is typically under 500 milliseconds.
Webhooks are the connective tissue between Codex and the rest of your toolchain. They enable workflows that would be awkward or impossible with polling: a code generation completes and automatically opens a pull request; a review finds a critical security issue and immediately pages the on-call engineer; a project index finishes and triggers a documentation rebuild. Because webhooks push data to you rather than requiring you to pull, they are more efficient than polling — your server only receives requests when there is something new to process. And because the payload includes the full event context, your handler does not need to make follow-up API calls to gather information — the data is right there in the request body.
Twelve event types span four categories. Subscribe to individual types or entire categories depending on how granular your workflow needs to be.
| Event Type | Category | Payload Summary | Typical Latency | Retries |
|---|---|---|---|---|
generation.completed |
Generation | Generation ID, code output, language, confidence | <500 ms | 5 |
generation.failed |
Generation | Generation ID, error code, prompt excerpt | <500 ms | 5 |
review.completed |
Review | Review ID, score, issue count by severity | <500 ms | 5 |
review.annotated |
Review | Review ID, file path, line range, issue details | <1 s | 5 |
review.failed |
Review | Review ID, error code, diff size | <500 ms | 5 |
project.indexed |
Project | Project ID, file count, index duration | <500 ms | 5 |
project.configured |
Project | Project ID, config diff (old vs new) | <500 ms | 5 |
project.deleted |
Project | Project ID, project name | <500 ms | 5 |
team.member_added |
Team | Team ID, member email, role | <500 ms | 5 |
team.member_removed |
Team | Team ID, member email | <500 ms | 5 |
team.key_created |
Team | Key ID (partial), key name, creator email | <500 ms | 5 |
team.key_revoked |
Team | Key ID (partial), key name, revoker email | <500 ms | 5 |
Generation events fire when a code generation request finishes — successfully or with an error. The completed payload includes the generated code, language, confidence score, and explanation. The failed payload includes the error code and a truncated prompt for debugging. Review events fire when a code review completes, when an individual annotation is produced (streaming mode), or when a review fails. The annotated event is sent per-file for large reviews, enabling real-time annotation streaming before the full review summary is available. Project events track the lifecycle of Codex project configurations: index completion, configuration changes, and project deletion. Team events track membership and API key lifecycle — useful for security automation like revoking access to internal systems when a team member is removed. All payloads include a timestamp in ISO 8601 UTC and an event_id (UUIDv7) for deduplication.
Every payload follows a consistent envelope structure. Your handler parses the envelope to route events, then processes the event-specific data inside.
The payload envelope contains four fields: event (the event type string), timestamp (ISO 8601 UTC), event_id (UUIDv7 for deduplication), and data (the event-specific payload object). The data object structure varies by event type but follows consistent patterns within each category. All timestamps in the data object are ISO 8601 UTC. All IDs are UUIDv7 strings in the data object. File paths use forward slashes regardless of platform. The content type is application/json with UTF-8 encoding. Codex sends three custom HTTP headers with every webhook request: X-Codex-Event (the event type), X-Codex-Signature (the HMAC-SHA256 hex digest), and X-Codex-Delivery (a unique delivery ID for tracing). Your server should respond with a 2xx status code within 10 seconds. Any response outside 2xx, or no response within 10 seconds, is treated as a delivery failure and triggers the retry sequence. The response body is ignored — Codex only checks the status code to determine success or failure.
Verifying the signature is the single most important step your webhook handler performs. Without it, anyone could POST fabricated events to your endpoint.
When you create a webhook subscription, you provide a secret string — any value between 16 and 256 characters. Codex uses this secret to compute an HMAC-SHA256 of the raw request body and sends the hex-encoded digest in the X-Codex-Signature header. Your handler reads the raw request body as bytes (before any JSON parsing), computes the same HMAC-SHA256 using your secret, and compares the result to the signature header. Use a constant-time comparison function to prevent timing attacks. If the signatures match, the payload is authentic and unmodified. If they do not match, discard the request and return a 401 status — someone may be probing your endpoint. The secret is never included in the request; it is a shared key that only you and Codex know. Rotate secrets periodically: create a new webhook subscription with the new secret, test it, then delete the old subscription. The official SDKs include helper functions for signature verification: codex.webhooks.verify(payload, signature, secret) in TypeScript, codex.webhooks.verify(payload, signature, secret) in Python, and equivalent methods in Go and Rust.
Codex delivers every event at least once. If your endpoint is unreachable, the retry system queues the event and tries again — five times, over six hours — before giving up.
The retry schedule uses exponential backoff: 1 minute after the first failure, 5 minutes after the second, 25 minutes after the third, 2 hours after the fourth, and 6 hours after the fifth. Between retries, the event is queued and does not block other webhook deliveries. If all five retries fail, the webhook endpoint is automatically disabled to prevent resource waste, and the account owner receives an email notification with the endpoint URL and the last error encountered. You can re-enable the endpoint from the dashboard or API after fixing the underlying issue. Delivery is at-least-once: Codex may deliver the same event more than once, particularly during retry storms or network partitions. Your handler must be idempotent — use the event_id field to deduplicate. Store processed event IDs in a database with a TTL of 72 hours (well beyond the 6-hour retry window) and skip events with IDs you have already processed. The delivery dashboard shows the status of every delivery attempt in the last 30 days, including HTTP status codes, response times, and retry timelines.
Webhooks unlock workflows that polling cannot. Here are patterns that Codex teams use in production to connect the platform to the rest of their toolchain.
The most common integration posts review results to communication platforms. Subscribe to review.completed, receive the score and issue breakdown, and format a Slack message or Jira comment. The message typically includes the review score as a color-coded indicator (green above 85, yellow above 70, red below 70), the top three issues by severity, and a link to the full review in the Codex dashboard. Another popular pattern is the automated PR workflow: subscribe to generation.completed, receive the generated code, and use the GitHub or GitLab API to create a pull request with the generated code as the diff. This enables "issue to PR" automation where a project manager labels an issue and Codex generates an implementation PR without an engineer touching a keyboard.
Security-focused teams subscribe to team.key_created and team.key_revoked to maintain an audit log of API key activity. Each event is forwarded to a SIEM system or a security information database. If a key is created outside of business hours, the handler triggers a Slack notification to the security channel. A more advanced pattern chains multiple events: when a review.completed event arrives with a score below a threshold, the handler calls the Codex API to generate a fix, then subscribes to generation.completed to receive the fix, then opens a PR with the generated fix — an automated remediation loop that closes the gap between finding an issue and proposing a solution.
Raúl C. Dominguez, DevOps Lead at Altitude Data in Phoenix, built a webhook-based quality pipeline: "We wired Codex webhooks into our internal event bus. Every review.completed event publishes to a Kafka topic that feeds our observability stack and our developer productivity dashboard. When a review score drops below our threshold, the event triggers an automated rollback of the deployment — no human in the loop, no waiting for someone to notice the dashboard. The signature verification gave our security team confidence that the events were genuine, and the idempotency design meant we never processed the same event twice even during network blips. The webhook system is the reason we can run Codex at scale across fourteen services without drowning in manual review overhead."
For best practices on securing webhook endpoints, the U.S. Digital Government resources include API security guidelines that apply to webhook receiver implementations.
Twelve events across four categories: generation (completed, failed), review (completed, annotated, failed), project (indexed, configured, deleted), and team (member_added, member_removed, key_created, key_revoked).
Generation events fire when a code generation request finishes, successfully or with an error. Review events cover the review lifecycle: completion with summary, per-file annotation (streaming), and failure. Project events track index builds, configuration changes, and project deletion. Team events monitor membership and API key activity for security automation. Each event type can be subscribed to individually. You can also subscribe to a category wildcard — for example, subscribing to review.* delivers all three review event types. The event catalog is versioned alongside the API; new event types are added with minor version bumps and never removed without a twelve-month deprecation window.
Compute the HMAC-SHA256 of the raw request body using your webhook secret. Compare the hex digest to the X-Codex-Signature header. Use constant-time comparison.
Verification is cryptographic proof that the payload originated from Codex and was not modified in transit. Your server receives the raw HTTP body as bytes. Before parsing JSON, compute HMAC-SHA256(secret, raw_body) and hex-encode the result. Compare this to the X-Codex-Signature header value using a constant-time comparison function — crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python, subtle.ConstantTimeCompare in Go. If the values do not match, return 401 and stop processing. The secret is set when you create the webhook subscription and is never included in the request — it is a pre-shared key known only to you and Codex. The webhook delivery dashboard includes the signature header for every delivery so you can debug verification failures by comparing the expected and received signatures offline. Rotate secrets by creating a new subscription and deleting the old one.
Codex retries five times with exponential backoff: 1 min, 5 min, 25 min, 2 hr, and 6 hr. After the fifth failure, the endpoint is disabled and you are notified by email.
The retry system is designed to survive transient failures — network blips, deployment restarts, load balancer failovers. After each failed attempt, the event is re-queued and retried after the backoff interval. The retries are independent per event — a single failing event does not block delivery of other events to the same endpoint. When an endpoint is disabled after five consecutive failures, pending events for that endpoint are discarded. You can re-enable the endpoint from the dashboard with one click, but discarded events are not re-sent. To avoid disabling during planned maintenance, you can temporarily pause a webhook endpoint from the dashboard — paused endpoints do not receive events and do not accumulate failures. The delivery dashboard shows the retry timeline for each failed event so you can correlate failures with your server's uptime history. For high-availability requirements, register multiple webhook endpoints for the same event types — Codex delivers to all of them independently.
Yes. Each subscription specifies event types and optionally filters by project ID. Your endpoint only receives events that match your filter criteria.
Filtering happens at the subscription level. When you create a webhook, you select which event types to include — from a single type like review.completed to a category wildcard like generation.*. You can also restrict the subscription to specific projects by listing their project IDs. Events from projects not in the list are silently dropped and never delivered to your endpoint. If you omit the project filter, the webhook receives events from all projects your account has access to. Filtering reduces noise on your endpoint and simplifies handler logic — you do not need to check the event type or project ID in your handler code because Codex already filtered upstream. The delivery dashboard shows filtered-but-not-delivered events with a "filtered" status so you can verify your filter configuration is correct. You can update filters on an existing subscription without changing the endpoint URL or secret.
The webhook system connects Codex events to your entire toolchain. Pair it with the API reference to build bidirectional integrations — webhooks notify you of events, the API lets you act on them. Ensure your environment is consistent from development through production with Docker containerization and CI/CD automation. Install the CLI and configure IDE plugins to generate the events your webhooks will consume. Explore AI code generation and automated code review for the capabilities that produce webhook events. The full documentation includes webhook payload schemas, example handlers in four languages, and a local testing guide. Organizations can compare plans, review security certifications, or contact the team for webhook architecture guidance.