diff --git a/api/webhook.yaml b/api/webhook.yaml
index 7c05983a1..0cbef52e3 100644
--- a/api/webhook.yaml
+++ b/api/webhook.yaml
@@ -98,9 +98,7 @@ paths:
       tags: [update]
       requestBody:
         description: |
-          This is the list of records to be adjusted.
-
-          TODO: Explain how this should be applied.
+          This is the list of changes to be applied.
         required: true
         content:
           application/external.dns.webhook+json;version=1:
@@ -135,14 +133,14 @@ components:
 
     endpoints:
       description: |
-        TODO: explain the endpoints array.
+        This is a list of DNS records.
       type: array
       items:
         $ref: '#/components/schemas/endpoint'
 
     endpoint:
       description: |
-        TODO: explain the endpoint object.
+        This is a DNS record.
       type: object
       properties:
         dnsName:
@@ -171,7 +169,8 @@ components:
 
     targets:
       description: |
-        TODO: explain the targets array.
+        This is the list of targets that this DNS record points to.
+        So for an A record it will be a list of IP addresses.
       type: array
       items:
         type: string
@@ -195,7 +194,11 @@ components:
 
     changes:
       description: |
-        TODO: explain the changes object.
+        This is the list of changes that need to be applied.  There are
+        four lists of endpoints.  The `create` and `delete` lists are lists
+        of records to create and delete respectively.  The `updateOld` and
+        `updateNew` lists are paired.  For each entry there's the old version
+        of the record and a new version of the record.
       type: object
       properties:
         create: