docs: clarify x-bf-async-webhook opt-in delivery and update async/webhook docs and OpenAPI spec

[Pratham-Mishra04]

Summary

Clarifies that webhook delivery for async jobs is opt-in per request, not automatic. Previously, the docs implied that registering an endpoint was sufficient for delivery to occur. This PR corrects that by documenting the x-bf-async-webhook header as the explicit trigger, and refines the behavior around subscription validation timing.

Changes

• Updated the async inference tip and webhook overview to state that the endpoint must be named via x-bf-async-webhook on the submit request for delivery to occur.
• Added a new "Webhook Notifications" section to async-inference.mdx detailing opt-in behavior, validation rules, and header scope.
• Added a new "Triggering a Delivery" section to webhooks.mdx with a curl example and clarifying bullet points.
• Corrected the OpenAPI description for x-bf-async-webhook to reflect that subscription validation happens at job completion time, not at submission — meaning a missing subscription no longer causes the submit to be rejected, but silently skips delivery instead.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Review the rendered documentation to confirm:

1. The async inference page includes the "Webhook Notifications" section with accurate opt-in behavior.
2. The webhooks page includes the "Triggering a Delivery" section with a working curl example.
3. The OpenAPI spec correctly reflects that subscription absence at job completion skips delivery rather than rejecting the submit.

Breaking changes

• Yes
• No

Related issues

Security considerations

None. No changes to auth, secrets, or delivery signing behavior.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Pratham-Mishra04]

• docs: clarify x-bf-async-webhook opt-in delivery and update async/webhook docs and OpenAPI spec #5429 👈 (View in Graphite)
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Clarified how to receive asynchronous inference results through webhooks instead of polling.
  • Added instructions for registering and selecting an enabled webhook endpoint when submitting a job.
  • Documented webhook subscription requirements, signed callbacks, and delivery behavior for completed or failed jobs.
  • Clarified that unsubscribed endpoints do not prevent job completion, but no webhook delivery is sent.

Walkthrough

Clarifies async webhook delivery as a per-request opt-in, documents endpoint and subscription requirements, updates submission examples, and aligns the OpenAPI description with behavior when event subscriptions are absent.

Changes

Async webhook documentation

Layer / File(s)	Summary
Webhook triggering contract docs/features/webhooks.mdx, docs/openapi/paths/inference/async.yaml	Documents endpoint naming, validation, per-job opt-in, subscription timing, and skipped delivery when subscriptions are unavailable.
Async inference usage guidance docs/features/async-inference.mdx	Updates polling guidance and curl examples to use x-bf-async-webhook, and explains webhook behavior during submission and polling.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• maximhq/bifrost#5250: Related async webhook documentation and OpenAPI behavior.
• maximhq/bifrost#5269: Related webhook workflow and async inference guidance.
• maximhq/bifrost#5270: Related x-bf-async-webhook and AsyncWebhookEndpoint semantics.

Suggested reviewers: akshaydeo, danpiths

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly summarizes the doc changes around opt-in webhook delivery and OpenAPI updates.
Description check	✅ Passed	Description follows the template and covers summary, changes, type, areas, testing, breaking changes, and security.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 07-21-docs_document_x-bf-async-webhook_header_and_fix_misleading_webhook_delivery_description

---

_{Comment @coderabbitai help to get the list of available commands.}

[Pratham-Mishra04]

Merge activity

• Jul 21, 6:29 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 21, 6:29 PM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/features/webhooks.mdx`:
- Around line 53-59: Update the curl example’s request body to use valid JSON by
replacing the `"messages": [...]` placeholder with a concrete message object
matching the format in async-inference documentation, while preserving the
existing webhook headers and request structure.

In `@docs/openapi/paths/inference/async.yaml`:
- Around line 750-754: The async webhook documentation must state that the
endpoint must remain both enabled and subscribed when the job completes;
otherwise delivery is skipped while the job still completes normally. Update the
endpoint-state description in docs/openapi/paths/inference/async.yaml lines
750-754 and the corresponding usage guidance in
docs/features/async-inference.mdx lines 173-175, keeping both documentation
layers consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 12013641-1d67-4780-8acb-9c5d13d6e258

📥 Commits

Reviewing files that changed from the base of the PR and between dca3ecc and dc8ff14.

📒 Files selected for processing (3)

• docs/features/async-inference.mdx
• docs/features/webhooks.mdx
• docs/openapi/paths/inference/async.yaml

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use valid JSON in the curl example.

"messages": [...] contains ..., which is invalid JSON, so copying this command fails before it can test webhook delivery. Use a concrete message object, consistent with docs/features/async-inference.mdx.

Proposed fix

-  -d '{ "model": "openai/gpt-4o-mini", "messages": [...] }'
+  -d '{
+    "model": "openai/gpt-4o-mini",
+    "messages": [
+      { "role": "user", "content": "Trigger an async webhook" }
+    ]
+  }'

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	```bash
	curl -X POST http://localhost:8080/v1/async/chat/completions \
	-H "Content-Type: application/json" \
	-H "x-bf-vk: sk-bf-your-virtual-key" \
	-H "x-bf-async-webhook: order-events" \
	-d '{ "model": "openai/gpt-4o-mini", "messages": [...] }'
	```

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/features/webhooks.mdx` around lines 53 - 59, Update the curl example’s
request body to use valid JSON by replacing the `"messages": [...]` placeholder
with a concrete message object matching the format in async-inference
documentation, while preserving the existing webhook headers and request
structure.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Keep completion-time endpoint state consistent across the documentation layers.

docs/features/webhooks.mdx requires the endpoint to remain enabled and subscribed when the job finishes. The two changed descriptions only mention the subscription requirement, so clarify that disabling the endpoint before completion skips delivery while the job still completes normally.

• docs/openapi/paths/inference/async.yaml#L750-L754: document the enabled-at-completion behavior alongside the subscription behavior.
• docs/features/async-inference.mdx#L173-L175: add the same completion-time enabled requirement to the usage guidance.

As per path instructions, documentation under docs/** must remain consistent with the documented runtime contract.

📍 Affects 2 files

• docs/openapi/paths/inference/async.yaml#L750-L754 (this comment)
• docs/features/async-inference.mdx#L173-L175

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/openapi/paths/inference/async.yaml` around lines 750 - 754, The async
webhook documentation must state that the endpoint must remain both enabled and
subscribed when the job completes; otherwise delivery is skipped while the job
still completes normally. Update the endpoint-state description in
docs/openapi/paths/inference/async.yaml lines 750-754 and the corresponding
usage guidance in docs/features/async-inference.mdx lines 173-175, keeping both
documentation layers consistent.

Source: Path instructions