Webhooks: give webhooks their own top-level section

fern/docs.yml

@@ -319,6 +319,55 @@ redirects:
   - source: /docs/platform/voice/sip/domain-applications
     destination: /docs/platform/voice/sip/sip-credentials
 
+  # Webhook reference pages moved out of their per-resource sections into one
+  # top-level Webhooks section. A callback like the SWAIG tool webhook fires for
+  # voice AI, Amazon Bedrock, sidecar agents, and text conversations alike, so
+  # filing it under Calls made a shared payload look channel-specific.
+  # One entry per moved page — the set is closed, since the old sections no
+  # longer exist and no new URL can appear beneath them.
+  - source: /docs/apis/rest/calls/webhooks/ai-swaig-tool-webhook
+    destination: /docs/apis/rest/webhooks/ai-swaig-tool-webhook
+  - source: /docs/apis/rest/calls/webhooks/swaig-signature-request
+    destination: /docs/apis/rest/webhooks/swaig-signature-request
+  - source: /docs/apis/rest/calls/webhooks/ai-post-prompt-callback
+    destination: /docs/apis/rest/webhooks/ai-post-prompt-callback
+  - source: /docs/apis/rest/calls/webhooks/ai-debug-webhook
+    destination: /docs/apis/rest/webhooks/ai-debug-webhook
+  - source: /docs/apis/rest/calls/webhooks/bedrock-swaig-tool-webhook
+    destination: /docs/apis/rest/webhooks/bedrock-swaig-tool-webhook
+  - source: /docs/apis/rest/calls/webhooks/bedrock-post-prompt-callback
+    destination: /docs/apis/rest/webhooks/bedrock-post-prompt-callback
+  - source: /docs/apis/rest/calls/webhooks/ai-sidecar-callback
+    destination: /docs/apis/rest/webhooks/ai-sidecar-callback
+  - source: /docs/apis/rest/calls/webhooks/ai-sidecar-swaig-tool-webhook
+    destination: /docs/apis/rest/webhooks/ai-sidecar-swaig-tool-webhook
+  - source: /docs/apis/rest/calls/webhooks/transcribe-status-callback
+    destination: /docs/apis/rest/webhooks/transcribe-status-callback
+  - source: /docs/apis/rest/calls/webhooks/stream-status-callback
+    destination: /docs/apis/rest/webhooks/stream-status-callback
+  - source: /docs/apis/rest/messages/webhooks/message-status-callback
+    destination: /docs/apis/rest/webhooks/message-status-callback
+  - source: /docs/apis/rest/campaign-registry/webhooks/ten-dlc-status-callback
+    destination: /docs/apis/rest/webhooks/ten-dlc-status-callback
+  - source: /docs/apis/rest/swml-webhook/webhooks/inbound-call-webhook
+    destination: /docs/apis/rest/webhooks/inbound-call-webhook
+  - source: /docs/apis/rest/swml-webhook/webhooks/inbound-message-webhook
+    destination: /docs/apis/rest/webhooks/inbound-message-webhook
+
+  # Each per-resource Webhooks section also answered on its own URL, returning a
+  # 307 to its first child. That landing is generated from the section, so it
+  # disappears with it — these four need entries of their own. Each points at the
+  # new location of the page it lands on today, so the destination is a real page
+  # in the same channel rather than an arbitrary first child.
+  - source: /docs/apis/rest/calls/webhooks
+    destination: /docs/apis/rest/webhooks/transcribe-status-callback
+  - source: /docs/apis/rest/messages/webhooks
+    destination: /docs/apis/rest/webhooks/message-status-callback
+  - source: /docs/apis/rest/campaign-registry/webhooks
+    destination: /docs/apis/rest/webhooks/ten-dlc-status-callback
+  - source: /docs/apis/rest/swml-webhook/webhooks
+    destination: /docs/apis/rest/webhooks/inbound-call-webhook
+
 check:
   rules:
     no-circular-redirects: error

fern/products/apis/apis.yml

@@ -72,20 +72,7 @@ navigation:
       - section: Calling
         skip-slug: true
         contents:
-          - calls:
-              - section: Webhooks
-                slug: webhooks
-                contents:
-                  - subpackage_calls.transcribe_status_callback
-                  - subpackage_calls.stream_status_callback
-                  - subpackage_calls.ai_sidecar_callback
-                  - subpackage_calls.ai_sidecar_swaig_tool_webhook
-                  - subpackage_calls.ai_swaig_tool_webhook
-                  - subpackage_calls.bedrock_swaig_tool_webhook
-                  - subpackage_calls.swaig_signature_request
-                  - subpackage_calls.ai_post_prompt_callback
-                  - subpackage_calls.ai_debug_webhook
-                  - subpackage_calls.bedrock_post_prompt_callback
+          - calls
           - queues
           - queueMembers
           - recordings
@@ -114,11 +101,7 @@ navigation:
       - section: Messaging
         skip-slug: true
         contents:
-          - messages:
-              - section: Webhooks
-                slug: webhooks
-                contents:
-                  - subpackage_messages.message_status_callback
+          - messages
           - section: Campaign Registry
             contents:
               - section: Brands
@@ -133,10 +116,6 @@ navigation:
                 referenced-packages:
                   - campaignRegistryPhoneNumberAssignments
                 contents: []
-              - section: Webhooks
-                slug: webhooks
-                contents:
-                  - subpackage_campaignRegistry.ten_dlc_status_callback
           - section: WhatsApp
             slug: whatsapp
             referenced-packages:
@@ -262,9 +241,37 @@ navigation:
             slug: swml-webhook
             referenced-packages:
               - swmlWebhook
+            contents: []
+      # Webhooks are grouped by channel rather than filed under the resource that
+      # configures them: a single callback is often shared across surfaces (a SWAIG
+      # tool webhook fires for voice AI, Amazon Bedrock, sidecar agents, and text
+      # conversations alike), so no one resource owns it. AI is its own group
+      # because it spans the channels; everything else sits under the channel it
+      # belongs to. The channel sections are skip-slug so every webhook keeps one
+      # flat, channel-agnostic URL.
+      - section: Webhooks
+        slug: webhooks
+        contents:
+          - section: AI
+            skip-slug: true
+            contents:
+              - subpackage_aiWebhooks.ai_swaig_tool_webhook
+              - subpackage_aiWebhooks.swaig_signature_request
+              - subpackage_aiWebhooks.ai_post_prompt_callback
+              - subpackage_aiWebhooks.ai_debug_webhook
+              - subpackage_aiWebhooks.bedrock_swaig_tool_webhook
+              - subpackage_aiWebhooks.bedrock_post_prompt_callback
+              - subpackage_aiWebhooks.ai_sidecar_callback
+              - subpackage_aiWebhooks.ai_sidecar_swaig_tool_webhook
+          - section: Calling
+            skip-slug: true
+            contents:
+              - subpackage_callingWebhooks.inbound_call_webhook
+              - subpackage_callingWebhooks.transcribe_status_callback
+              - subpackage_callingWebhooks.stream_status_callback
+          - section: Messaging
+            skip-slug: true
             contents:
-              - section: Webhooks
-                slug: webhooks
-                contents:
-                  - subpackage_swmlWebhook.inbound_call_webhook
-                  - subpackage_swmlWebhook.inbound_message_webhook
+              - subpackage_messagingWebhooks.inbound_message_webhook
+              - subpackage_messagingWebhooks.message_status_callback
+              - subpackage_messagingWebhooks.ten_dlc_status_callback

fern/products/platform/pages/ai/guides/tool-calling/index.mdx

@@ -21,10 +21,10 @@ max-toc-depth: 3
 [contexts-workflows]: /docs/server-sdks/guides/contexts-workflows
 [toggle-functions]: /docs/swml/guides/toggle-functions
 [context-switch]: /docs/swml/guides/context-switch
-[swaig-webhook]: /docs/apis/rest/calls/webhooks/ai-swaig-tool-webhook
+[swaig-webhook]: /docs/apis/rest/webhooks/ai-swaig-tool-webhook
 [swaig-includes]: /docs/swml/reference/calling/ai/swaig/includes
 [sdk-includes]: /docs/server-sdks/reference/python/agents/agent-base/add-function-include
-[signature-webhook]: /docs/apis/rest/calls/webhooks/swaig-signature-request
+[signature-webhook]: /docs/apis/rest/webhooks/swaig-signature-request
 
 Ask a language model what a ride across town costs, with nothing else to go on, and it will give you
 a number. The number will sound right. That doesn't make it the fare you charge.

fern/products/platform/pages/platform/core/webhooks/index.mdx

@@ -150,13 +150,13 @@ For critical paths, use a mechanism whose failure modes are visible to your appl
 <CardGroup cols={2}>
 <Card
   title="Message status callback"
-  href="/docs/apis/rest/messages/webhooks/message-status-callback"
+  href="/docs/apis/rest/webhooks/message-status-callback"
 >
   The full field reference and status values for outbound message status callbacks.
 </Card>
 <Card
   title="10DLC status callback"
-  href="/docs/apis/rest/campaign-registry/webhooks/ten-dlc-status-callback"
+  href="/docs/apis/rest/webhooks/ten-dlc-status-callback"
 >
   Receive 10DLC campaign registration status updates via webhooks.
 </Card>

fern/products/swml/pages/reference/methods/calling/ai/ai_params/index.mdx

@@ -600,5 +600,5 @@ the rest, since the set grows over time.
 
 <WebhookPayloadSnippet webhook="aiDebugWebhook" />
 
-See the [AI debug webhook](/docs/apis/rest/calls/webhooks/ai-debug-webhook) webhook page for the full
+See the [AI debug webhook](/docs/apis/rest/webhooks/ai-debug-webhook) webhook page for the full
 field reference.

fern/products/swml/pages/reference/methods/calling/ai/ai_swaig/functions/index.mdx

@@ -110,11 +110,11 @@ object or an array — telling the agent what to do.
 
 ### Request
 
-<Schema type="Calling.AiSwaigToolWebhookPayload" api="signalwire-rest" showDescription />
+<Schema type="Webhooks.AI.AiSwaigToolWebhookPayload" api="signalwire-rest" showDescription />
 
 <WebhookPayloadSnippet webhook="aiSwaigToolWebhook" />
 
-See the [AI SWAIG tool webhook](/docs/apis/rest/calls/webhooks/ai-swaig-tool-webhook) webhook page for the full field reference.
+See the [AI SWAIG tool webhook](/docs/apis/rest/webhooks/ai-swaig-tool-webhook) webhook page for the full field reference.
 
 ### Reply
 

fern/products/swml/pages/reference/methods/calling/ai/ai_swaig/includes/index.mdx

@@ -126,7 +126,7 @@ configured—giving your server the context it needs to respond appropriately.
 
 <WebhookPayloadSnippet webhook="swaigSignatureRequest" />
 
-See the [SWAIG function signature request](/docs/apis/rest/calls/webhooks/swaig-signature-request)
+See the [SWAIG function signature request](/docs/apis/rest/webhooks/swaig-signature-request)
 webhook page for the full field reference.
 
 <Note>

fern/products/swml/pages/reference/methods/calling/ai/index.mdx

@@ -170,7 +170,7 @@ SignalWire sends the report to your `post_prompt_url` as an HTTP `POST`.
 
 <WebhookPayloadSnippet webhook="aiPostPromptCallback" />
 
-See the [AI post-prompt callback](/docs/apis/rest/calls/webhooks/ai-post-prompt-callback) webhook
+See the [AI post-prompt callback](/docs/apis/rest/webhooks/ai-post-prompt-callback) webhook
 page for the full field reference.
 
 ### Responding to post prompt requests

fern/products/swml/pages/reference/methods/calling/ai_sidecar/index.mdx

@@ -207,7 +207,7 @@ The actual event is under `sidecar_event` — unwrap that in your code before re
 
 <WebhookPayloadSnippet webhook="aiSidecarCallback" />
 
-See the [AI sidecar callback](/docs/apis/rest/calls/webhooks/ai-sidecar-callback) webhook page for the full payload reference. The per-`type` fields are listed below.
+See the [AI sidecar callback](/docs/apis/rest/webhooks/ai-sidecar-callback) webhook page for the full payload reference. The per-`type` fields are listed below.
 
 ### Callback types
 
@@ -274,7 +274,7 @@ caller details under `channel_data`.
 
 <WebhookPayloadSnippet webhook="aiSidecarSwaigToolWebhook" />
 
-See the [AI sidecar SWAIG tool webhook](/docs/apis/rest/calls/webhooks/ai-sidecar-swaig-tool-webhook) webhook page for the full field reference.
+See the [AI sidecar SWAIG tool webhook](/docs/apis/rest/webhooks/ai-sidecar-swaig-tool-webhook) webhook page for the full field reference.
 
 ### Response
 

fern/products/swml/pages/reference/methods/calling/bedrock/index.mdx

@@ -119,7 +119,7 @@ SignalWire sends the report to your `post_prompt_url` as an HTTP `POST`.
 
 <WebhookPayloadSnippet webhook="bedrockPostPromptCallback" />
 
-See the [Amazon Bedrock post-prompt callback](/docs/apis/rest/calls/webhooks/bedrock-post-prompt-callback)
+See the [Amazon Bedrock post-prompt callback](/docs/apis/rest/webhooks/bedrock-post-prompt-callback)
 webhook page for the full field reference.
 
 ### Responding to post prompt requests

fern/products/swml/pages/reference/methods/calling/bedrock/swaig/functions/index.mdx

@@ -75,7 +75,7 @@ object or an array — telling the agent what to do.
 
 ### Request
 
-<Schema type="Calling.BedrockSwaigToolWebhookPayload" api="signalwire-rest" showDescription />
+<Schema type="Webhooks.AI.BedrockSwaigToolWebhookPayload" api="signalwire-rest" showDescription />
 
 <Note>
 This payload differs from the one an [`ai`](/docs/swml/reference/calling/ai) agent sends. `content_type`
@@ -87,7 +87,7 @@ Write your handler against this list, not the `ai` one.
 
 <WebhookPayloadSnippet webhook="bedrockSwaigToolWebhook" />
 
-See the [Amazon Bedrock SWAIG tool webhook](/docs/apis/rest/calls/webhooks/bedrock-swaig-tool-webhook)
+See the [Amazon Bedrock SWAIG tool webhook](/docs/apis/rest/webhooks/bedrock-swaig-tool-webhook)
 webhook page for the full field reference.
 
 ### Reply

fern/products/swml/pages/reference/methods/calling/send_sms.mdx

@@ -110,7 +110,7 @@ The callback uses the same payload as other outbound messages sent through Signa
 
 <WebhookPayloadSnippet webhook="messageStatusCallback" />
 
-See the [Message status callback](/docs/apis/rest/messages/webhooks/message-status-callback)
+See the [Message status callback](/docs/apis/rest/webhooks/message-status-callback)
 webhook page for the full field reference and the list of possible `status` values.
 
 ## **Examples**

fern/products/swml/pages/reference/methods/calling/stream.mdx

@@ -85,7 +85,7 @@ When you set `status_url`, SignalWire POSTs a `calling.call.stream` event to it
 
 <WebhookPayloadSnippet webhook="streamStatusCallback" />
 
-See the [Stream status callback](/docs/apis/rest/calls/webhooks/stream-status-callback) webhook page for the full field reference.
+See the [Stream status callback](/docs/apis/rest/webhooks/stream-status-callback) webhook page for the full field reference.
 
 ---
 

fern/products/swml/pages/reference/methods/calling/transcribe.mdx

@@ -47,7 +47,7 @@ When you set `status_url`, SignalWire POSTs a transcript event to it when the ca
 
 <WebhookPayloadSnippet webhook="transcribeStatusCallback" />
 
-See the [Transcript status callback](/docs/apis/rest/calls/webhooks/transcribe-status-callback) webhook page for the full field reference.
+See the [Transcript status callback](/docs/apis/rest/webhooks/transcribe-status-callback) webhook page for the full field reference.
 
 ---
 

fern/products/swml/pages/reference/methods/messaging/overview.mdx

@@ -25,7 +25,7 @@ steps** per inbound message; once that ceiling is hit, execution stops.
 ## Webhook and variable payload [#webhook-payload]
 
 When SignalWire fetches a Messaging SWML document from an external URL, it POSTs the
-[inbound message webhook payload](/docs/apis/rest/swml-webhook/webhooks/inbound-message-webhook)
+[inbound message webhook payload](/docs/apis/rest/webhooks/inbound-message-webhook)
 to your server — on the initial inbound-message fetch and on every fetch triggered by a
 [`transfer`](/docs/swml/reference/messaging/transfer) step. Your server must respond with a valid
 SWML document using one of these content types: `application/json`, `application/yaml`, or

fern/products/swml/pages/reference/methods/messaging/reply.mdx

@@ -151,7 +151,7 @@ through SignalWire:
 
 <WebhookPayloadSnippet webhook="messageStatusCallback" />
 
-See the [Message status callback](/docs/apis/rest/messages/webhooks/message-status-callback)
+See the [Message status callback](/docs/apis/rest/webhooks/message-status-callback)
 webhook page for the full field reference and the list of possible `status` values.
 
 ## **Examples**

fern/products/swml/pages/reference/methods/messaging/transfer.mdx

@@ -42,7 +42,7 @@ inline document.
 ## **Webhook payload sent to `dest`**
 
 When `transfer` fetches an external document, SignalWire `POST`s the
-[inbound message webhook payload](/docs/apis/rest/swml-webhook/webhooks/inbound-message-webhook)
+[inbound message webhook payload](/docs/apis/rest/webhooks/inbound-message-webhook)
 to `dest`:
 
 - `message` — the original inbound message that triggered this SWML document.

specs/signalwire-rest/calling-api/calls/main.tsp

@@ -5,37 +5,13 @@ import "../../../_shared/alias/token-permissions.tsp";
 import "./models/requests.tsp";
 import "./models/responses.tsp";
 import "./models/examples.tsp";
-import "./models/webhooks.tsp";
 import "../tags.tsp";
-import "../../../_shared/webhook/decorator.tsp";
 
 using TypeSpec.Http;
 using TypeSpec.OpenAPI;
 using Types.StatusCodes;
 
 @route("/calls")
-@webhook("transcribeStatusCallback", TranscribeStatusCallbackPayload, CALLS_TAG)
-@webhook("streamStatusCallback", StreamStatusCallbackPayload, CALLS_TAG)
-@webhook("aiSidecarCallback", AISidecarCallbackPayload, CALLS_TAG)
-@webhook(
-  "aiSidecarSwaigToolWebhook",
-  AISidecarSwaigToolWebhookPayload,
-  CALLS_TAG
-)
-@webhook("aiSwaigToolWebhook", AiSwaigToolWebhookPayload, CALLS_TAG)
-@webhook("swaigSignatureRequest", SwaigSignatureRequestPayload, CALLS_TAG)
-@webhook(
-  "bedrockSwaigToolWebhook",
-  BedrockSwaigToolWebhookPayload,
-  CALLS_TAG
-)
-@webhook("aiPostPromptCallback", AiPostPromptCallbackPayload, CALLS_TAG)
-@webhook("aiDebugWebhook", AiDebugWebhookPayload, CALLS_TAG)
-@webhook(
-  "bedrockPostPromptCallback",
-  BedrockPostPromptCallbackPayload,
-  CALLS_TAG
-)
 namespace SignalWireAPI.Calling.Calls {
   @tag(CALLS_TAG)
   @friendlyName("Calls")