diff --git a/src/openapi.yaml b/src/openapi.yaml
index 3da70df7..098f9dac 100644
--- a/src/openapi.yaml
+++ b/src/openapi.yaml
@@ -519,6 +519,82 @@ paths:
                       message: Error definition 999 not found
                     requestId: req-errors-delete-404
                     timestamp: "2026-07-27T09:15:00.000Z"
+  /api/webhooks:
+    post:
+      summary: Register a webhook
+      description: Registers a new webhook for the authenticated developer.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+            examples:
+              registerWebhook:
+                summary: Register a webhook for API and balance events
+                value:
+                  developerId: "dev-123"
+                  url: "https://example.com/webhook"
+                  events:
+                    - "new_api_call"
+                    - "low_balance_alert"
+                  secret: "my_super_secret"
+                  retryPolicy:
+                    maxRetries: 3
+                    initialIntervalMs: 1000
+                    backoffFactor: 2.0
+      responses:
+        "201":
+          description: Webhook registered successfully
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                registered:
+                  summary: Successfully registered
+                  value:
+                    message: Webhook registered successfully.
+                    developerId: "dev-123"
+                    url: "https://example.com/webhook"
+                    events:
+                      - "new_api_call"
+                      - "low_balance_alert"
+  /api/webhooks/{developerId}:
+    get:
+      summary: Get webhook config
+      description: Returns the webhook configuration for the given developer.
+      responses:
+        "200":
+          description: Webhook configuration
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                found:
+                  summary: Webhook config
+                  value:
+                    developerId: "dev-123"
+                    url: "https://example.com/webhook"
+                    events:
+                      - "new_api_call"
+                      - "low_balance_alert"
+                    retryPolicy:
+                      maxRetries: 3
+                      initialIntervalMs: 1000
+                      backoffFactor: 2.0
+        "404":
+          description: Webhook not found
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                notFound:
+                  summary: No webhook registered
+                  value:
+                    message: "No webhook registered for this developer."
 components:
   securitySchemes:
     bearerAuth:
diff --git a/src/routes/webhooks/openapi-yaml.test.ts b/src/routes/webhooks/openapi-yaml.test.ts
new file mode 100644
index 00000000..37daeda6
--- /dev/null
+++ b/src/routes/webhooks/openapi-yaml.test.ts
@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+describe('src/openapi.yaml — webhooks examples', () => {
+  const yamlPath = path.join(process.cwd(), 'src', 'openapi.yaml');
+
+  test('documents GET /api/webhooks/{developerId} endpoint', () => {
+    const content = fs.readFileSync(yamlPath, 'utf8');
+    expect(content).toContain('/api/webhooks/{developerId}');
+    expect(content).toContain('Get webhook config');
+  });
+
+  test('documents POST /api/webhooks endpoint', () => {
+    const content = fs.readFileSync(yamlPath, 'utf8');
+    expect(content).toContain('/api/webhooks');
+    expect(content).toContain('Register a webhook');
+  });
+
+  test('includes register and get response examples for webhooks', () => {
+    const content = fs.readFileSync(yamlPath, 'utf8');
+    expect(content).toContain('Register a webhook for API and balance events');
+    expect(content).toContain('Successfully registered');
+    expect(content).toContain('Webhook config');
+    expect(content).toContain('No webhook registered');
+    expect(content).toContain('new_api_call');
+    expect(content).toContain('low_balance_alert');
+  });
+});