Minor changes to webhooks docs

docs/using-the-api/webhooks/create-consumer.md

@@ -1,21 +1,28 @@
 ---
-title: "Manage webhook consumers to subscribe to events"
-sidebar_label: "Manage webhook consumers"
-description: "Create new webhook consumers and manage existing ones to receive webhooks using the Portal or the API"
+title: "Build webhook consumers to subscribe to events"
+sidebar_label: "Consume webhooks"
+description: "Configure new webhook consumers in Codat and manage existing configuration to receive webhook events"
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem"
 
-## Create a webhook consumer
+## Overview
 
-To start listening to messages we send you, configure your webhook consumer endpoints. Navigate to **Settings > Webhooks > Events > Configure consumer** and click **Add endpoint** to create a new consumer. 
+A _webhook consumer_ is your implementation of a POST endpoint that you built to receive Codat's webhooks. In general, you need one consumer per [event type](/using-the-api/webhooks/event-types).
 
-Add the endpoint URL that you want to receive the messages, an optional description, and choose the events that this endpoint should listen to. If you don't specify the event types, your endpoint will receive all events by default. 
+This consumer must process the event within 15 seconds when it receives a POST request. We recommend passing the event to an internal message queue so that you can process it in time.
+
+## Configure webhook consumer
+
+Once you have built your webhook consumer, configure Codat to send events to this consumer. 
+Navigate to **Settings > Webhooks > Events > Configure consumer** and click **Add endpoint** to create a new consumer. 
+
+Add the endpoint URL that you want to receive the messages, an optional description, and choose the events that this endpoint should listen to. You must specify a least one event type per endpoint. 
 
 Browse our event catalog [in the Portal](https://app.codat.io/monitor/events) or in our [documentation](/using-the-api/webhooks/event-types) to choose the event types that suit your use case. 
 
-:::tip Create a consumer via the API
+:::tip Configure a consumer via the API
 
 You can create a webhook consumer programmatically using our [Create webhook](/platform-api#/operations/create-webhook-consumer) endpoint.
 
@@ -422,4 +429,4 @@ svix verify --secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw --msg-id msg_p5jXN8A
 
 - [Event types](/using-the-api/webhooks/event-types)
 - [Migration guide](/using-the-api/webhooks/migration-guide)
-- [Troubleshooting](/using-the-api/webhooks/troubleshooting)
+- [Troubleshooting](/using-the-api/webhooks/troubleshooting)

docs/using-the-api/webhooks/event-types.md

@@ -34,4 +34,4 @@ The names of our new event types differ from our legacy rule types. We added the
 ---
 ## Read next
 
-- See how you can [consume webhooks and manage consumers](/using-the-api/webhooks/create-event) using the Portal or our API
+- See how you can [consume webhooks and manage consumers](/using-the-api/webhooks/create-consumer) using the Portal or our API

docs/using-the-api/webhooks/overview.md

@@ -8,25 +8,26 @@ _Webhooks_ are an automated way for an app to notify you when a specific event o
 
 We refer to the HTTP endpoints that you configure to subscribe to Codat's events as _webhook consumers_. A `200` response from the consumer indicates that the webhook message was successfully received. 
 
-With our new webhook service, you can leverage the following benefits:
+With our webhook service, you can leverage the following benefits:
 
 - Automatic retries of failed webhook deliveries according to our [retry schedule](/using-the-api/webhooks/troubleshooting#retry-policy)
 - Detailed event logging with a full overview of delivery attempts and payloads
-- Easy event replay to reprocess past events or retry failed events
+- Make your solution robust with easy event replay to reprocess past events or retry failed events
 - Mock event functionality to simplify your testing and development
-- Robust, reliable, stable solution to support your critical operations
 
-## Already using our webhooks?
+:::note Using our legacy webhooks? 
 
-If you are currently using our legacy webhook service, its relevant documentation is still available: 
+If you have been using our webhooks before March 6, 2024, we recommend migrating them to the new service.
+See how you can migrate in our [migration guide](/using-the-api/webhooks/migration-guide).
+
+You can view the old webhook service documentation here: 
 
 - [View rule types](/using-the-api/webhooks/legacy/core-rules-types)
 - [Create or update rules](/using-the-api/webhooks/legacy/core-rules-create)
 - [Listen to events](/using-the-api/webhooks/legacy/core-rules-webhooks)
 - [Webhook security](/using-the-api/webhooks/legacy/core-rules-webhooksecurity)
 - [Receive webhook events as emails](/using-the-api/webhooks/legacy/receive-webhooks-as-email)
-
-Look through our [migration guide](/using-the-api/webhooks/migration-guide) to see details of migration options if you are interested in using our new webhook service. 
+:::
 
 ---
 

sidebars/use-the-api.js

@@ -51,8 +51,8 @@ module.exports = [
       "using-the-api/webhooks/overview",
       "using-the-api/webhooks/event-types",
       "using-the-api/webhooks/create-consumer",
-      "using-the-api/webhooks/migration-guide",
       "using-the-api/webhooks/troubleshooting",
+      "using-the-api/webhooks/migration-guide",
       {
         type: "category",
         label: "Legacy webhooks",