@agility/management-sdk 0.1.39 → 0.2.0-beta.2

package/docs/webhook-methods.md

@@ -2,437 +2,337 @@
 
 ## WebhookMethods
 
-This class provides comprehensive webhook management operations for Agility CMS. Webhooks allow you to receive real-time notifications when specific events occur in your CMS, enabling integration with external systems and automated workflows.
+This class provides webhook management operations for Agility CMS. Webhooks deliver real-time HTTP POST notifications to your endpoints when content is saved, published, or moved through workflow, enabling integration with external systems and automated builds.
 
 **Important Notes:**
-- Webhooks provide real-time event notifications to external endpoints
-- Each webhook can be configured to trigger on specific events
-- Webhooks support various event types (content changes, page updates, etc.)
-- Webhook URLs must be accessible and return appropriate HTTP status codes
-- Failed webhook deliveries are automatically retried with exponential backoff
-- Webhooks can be secured with authentication headers or signatures
+- Webhooks fire on three event categories: content save, content publish, and content workflow events — each can be toggled per webhook
+- Webhook IDs are string GUIDs (the `rowKey` of the stored record), not numbers
+- Signed delivery is **opt-in per webhook** (`secureDeliveryEnabled`, off by default): when enabled, deliveries carry [Standard Webhooks](https://www.standardwebhooks.com/) signature headers — see [Verifying deliveries](#verifying-deliveries-signing) below. Webhooks with it off (including every webhook created before the feature shipped) are delivered unsigned, exactly as before
+- List responses never include signing secrets; `getWebhook` masks the signing secret unless the caller has *FullControl* permission on webhooks
+- Rotating a signing secret requires *FullControl* permission; reading delivery history requires *Manage* permission
+- Failed deliveries are retried automatically when retries are enabled — see [Retry behavior](#retry-behavior)
 
 ### Function List
+- [webhookList](#webhooklist) - Retrieves a paged list of webhooks
 - [getWebhook](#getwebhook) - Retrieves a specific webhook by ID
-- [webhookList](#webhooklist) - Retrieves list of all webhooks
 - [saveWebhook](#savewebhook) - Creates or updates a webhook
 - [deleteWebhook](#deletewebhook) - Deletes a webhook by ID
+- [getWebhookHistory](#getwebhookhistory) - Retrieves the delivery history for a webhook
+- [rotateWebhookSecret](#rotatewebhooksecret) - Rotates a webhook's signing secret
+
+### Reference
+- [The Webhook object](#the-webhook-object)
+- [Verifying deliveries (signing)](#verifying-deliveries-signing)
+- [Retry behavior](#retry-behavior)
 
 ---
 
-### getWebhook
+### webhookList
 
-Retrieves a specific webhook by its unique ID.
+Retrieves a paged list of webhooks for the instance. Uses continuation-token paging: pass the `token` from a previous response to fetch the next page. Signing secrets are always stripped from list responses.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `webhookID` | `number` | Yes | The webhook ID to retrieve |
 | `guid` | `string` | Yes | Current website GUID |
+| `take` | `number` | No | Number of records to take (default: 20) |
+| `token` | `string` | No | Continuation token from a previous response (default: null) |
 
-**Returns:** `Webhook` - Complete webhook object with configuration and statistics
+**Returns:** `TokenPagedResult<Webhook>` - `{ token, items }` where `token` is the continuation token for the next page (or null when there are no more results) and `items` is the array of webhooks
 
 **Usage Example:**
 ```typescript
-const webhook = await apiClient.webhookMethods.getWebhook(123, guid);
-console.log('Webhook name:', webhook.name);
-console.log('Webhook URL:', webhook.url);
-console.log('Events:', webhook.events);
-console.log('Active:', webhook.isActive);
-console.log('Created:', webhook.createdDate);
-console.log('Last triggered:', webhook.lastTriggered);
-
-// Display webhook statistics
-if (webhook.statistics) {
-    console.log('Statistics:');
-    console.log(`  Total deliveries: ${webhook.statistics.totalDeliveries}`);
-    console.log(`  Successful deliveries: ${webhook.statistics.successfulDeliveries}`);
-    console.log(`  Failed deliveries: ${webhook.statistics.failedDeliveries}`);
-    console.log(`  Success rate: ${webhook.statistics.successRate}%`);
-}
+// First page
+let page = await apiClient.webhookMethods.webhookList(guid, 20);
+page.items.forEach(webhook => {
+    console.log(`${webhook.name} -> ${webhook.url} (enabled: ${webhook.enabled})`);
+});
 
-// Display webhook configuration
-console.log('Configuration:');
-console.log(`  Method: ${webhook.method}`);
-console.log(`  Content Type: ${webhook.contentType}`);
-console.log(`  Timeout: ${webhook.timeout}ms`);
-console.log(`  Retry count: ${webhook.retryCount}`);
-
-// Check authentication
-if (webhook.authentication) {
-    console.log('Authentication enabled:');
-    console.log(`  Type: ${webhook.authentication.type}`);
-    console.log(`  Headers: ${Object.keys(webhook.authentication.headers).join(', ')}`);
-} else {
-    console.log('No authentication configured');
+// Fetch all pages
+const allWebhooks = [...page.items];
+while (page.token) {
+    page = await apiClient.webhookMethods.webhookList(guid, 20, page.token);
+    allWebhooks.push(...page.items);
 }
+console.log(`Total webhooks: ${allWebhooks.length}`);
 ```
 
-**Response Properties:**
-The `Webhook` object includes:
-- `webhookID`: Unique identifier for the webhook
-- `name`: Human-readable name for the webhook
-- `url`: Target URL for webhook deliveries
-- `events`: Array of events that trigger the webhook
-- `isActive`: Whether the webhook is active
-- `method`: HTTP method (GET, POST, PUT, etc.)
-- `contentType`: Content type for webhook payload
-- `timeout`: Request timeout in milliseconds
-- `retryCount`: Number of retry attempts for failed deliveries
-- `authentication`: Authentication configuration
-- `statistics`: Delivery statistics and metrics
-
 **Error Handling:**
-- Throws `Exception` when webhook not found
+- Throws `Exception` when retrieval fails
 
-### webhookList
+### getWebhook
 
-Retrieves a list of all webhooks in the current website.
+Retrieves a specific webhook by its ID (the `rowKey` GUID).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `guid` | `string` | Yes | Current website GUID |
-| `take` | `number` | No | Number of records to take (default: 20) |
-| `token` | `string` | No | Token parameter (default: null) |
+| `webhookID` | `string` | Yes | The webhook ID (`rowKey`) to retrieve |
 
-**Returns:** `any` - Array of all webhooks
+**Returns:** `Webhook` - The webhook object. The `signingSecret` is masked unless the caller has *FullControl* permission on webhooks — the same bar as rotating it.
 
 **Usage Example:**
 ```typescript
-const webhooks = await apiClient.webhookMethods.getWebhookList(guid);
-console.log(`Total webhooks: ${webhooks.length}`);
-
-// Display webhook summary
-webhooks.forEach(webhook => {
-    console.log(`Webhook: ${webhook.name}`);
-    console.log(`  URL: ${webhook.url}`);
-    console.log(`  Events: ${webhook.events.join(', ')}`);
-    console.log(`  Active: ${webhook.isActive ? 'Yes' : 'No'}`);
-    console.log(`  Last triggered: ${webhook.lastTriggered || 'Never'}`);
-    console.log('---');
-});
-
-// Filter active webhooks
-const activeWebhooks = webhooks.filter(w => w.isActive);
-const inactiveWebhooks = webhooks.filter(w => !w.isActive);
-console.log(`Active webhooks: ${activeWebhooks.length}`);
-console.log(`Inactive webhooks: ${inactiveWebhooks.length}`);
-
-// Group webhooks by event type
-const webhooksByEvent = webhooks.reduce((acc, webhook) => {
-    webhook.events.forEach(event => {
-        if (!acc[event]) acc[event] = [];
-        acc[event].push(webhook);
-    });
-    return acc;
-}, {});
-
-console.log('Webhooks by event:');
-Object.entries(webhooksByEvent).forEach(([event, eventWebhooks]) => {
-    console.log(`  ${event}: ${eventWebhooks.length} webhooks`);
+const webhook = await apiClient.webhookMethods.getWebhook(guid, webhookID);
+console.log('Webhook name:', webhook.name);
+console.log('Webhook URL:', webhook.url);
+console.log('Enabled:', webhook.enabled);
+console.log('Events:', {
+    save: webhook.contentSaveEvents,
+    publish: webhook.contentPublishEvents,
+    workflow: webhook.contentWorkflowEvents
 });
-
-// Find webhooks with high failure rates
-const failingWebhooks = webhooks.filter(webhook => 
-    webhook.statistics && webhook.statistics.successRate < 90
-);
-console.log(`Webhooks with high failure rate: ${failingWebhooks.length}`);
-
-// Create webhook dropdown options
-const webhookOptions = webhooks.map(webhook => ({
-    value: webhook.webhookID,
-    label: webhook.name,
-    url: webhook.url,
-    active: webhook.isActive
-}));
+console.log('Retries:', webhook.retriesEnabled
+    ? `${webhook.retryCount} retries at ${webhook.retrySpeed} speed`
+    : 'disabled');
 ```
 
-**Common Webhook Events:**
-- `content.created`: New content item created
-- `content.updated`: Content item updated
-- `content.deleted`: Content item deleted
-- `content.published`: Content item published
-- `content.unpublished`: Content item unpublished
-- `page.created`: New page created
-- `page.updated`: Page updated
-- `page.deleted`: Page deleted
-- `page.published`: Page published
-- `page.unpublished`: Page unpublished
-- `model.created`: Content model created
-- `model.updated`: Content model updated
-- `asset.uploaded`: Asset uploaded
-- `asset.updated`: Asset updated
-
 **Error Handling:**
-- Throws `Exception` when retrieval fails
+- Throws `Exception` when the webhook is not found or retrieval fails
 
 ### saveWebhook
 
 Creates a new webhook or updates an existing one.
 
+**To update an existing webhook, the `partitionKey` and `rowKey` from a previously retrieved webhook must be present on the object** — without them the API treats the save as a create and mints a new webhook. The easiest pattern is get → modify → save.
+
+Signed delivery is opt-in per webhook: set `secureDeliveryEnabled: true` and the server mints a signing secret on that save (webhooks with it off — including every webhook created before this feature — are delivered unsigned, exactly as before). Any `signingSecret` value you send is ignored; secrets are always server-controlled. Use [rotateWebhookSecret](#rotatewebhooksecret) to change one.
+
+The response sets **`signingSecretJustCreated: true`** on exactly the save that mints the secret, so you can tell a newly created secret from one that was already there. It is a property of the response, never of the stored webhook — `getWebhook` never returns it. Note that flipping `secureDeliveryEnabled` off and back on does **not** mint a new secret: the original is retained, and the flag stays `false`.
+
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `webhook` | `Webhook` | Yes | Webhook object to save |
 | `guid` | `string` | Yes | Current website GUID |
+| `webhook` | `Webhook` | Yes | Webhook object to save |
 
-**Returns:** `Webhook` - Saved webhook object with updated metadata
+**Returns:** `Webhook` - The saved webhook object
 
 **Usage Example:**
 ```typescript
+import { Webhook } from '@agility/management-sdk';
+
 // Create a new webhook
-const newWebhook = {
-    name: 'Content Update Notification',
-    url: 'https://api.example.com/webhooks/agility-content',
-    events: [
-        'content.created',
-        'content.updated',
-        'content.published'
-    ],
-    isActive: true,
-    method: 'POST',
-    contentType: 'application/json',
-    timeout: 30000,
-    retryCount: 3,
-    authentication: {
-        type: 'header',
-        headers: {
-            'Authorization': 'Bearer your-api-token',
-            'X-API-Key': 'your-api-key'
-        }
-    }
-};
-
-const savedWebhook = await apiClient.webhookMethods.saveWebhook(newWebhook, guid);
-console.log('Webhook created with ID:', savedWebhook.webhookID);
-
-// Update existing webhook
-const existingWebhook = await apiClient.webhookMethods.getWebhook(123, guid);
-existingWebhook.name = 'Updated Webhook Name';
-existingWebhook.url = 'https://api.example.com/webhooks/updated-endpoint';
-existingWebhook.events.push('page.published');
-
-const updatedWebhook = await apiClient.webhookMethods.saveWebhook(existingWebhook, guid);
-console.log('Webhook updated:', updatedWebhook.name);
-
-// Create webhook with custom payload template
-const customWebhook = {
-    name: 'Custom Payload Webhook',
-    url: 'https://api.example.com/webhooks/custom',
-    events: ['content.published'],
-    isActive: true,
-    method: 'POST',
-    contentType: 'application/json',
-    timeout: 15000,
-    retryCount: 2,
-    payloadTemplate: {
-        eventType: '{{event}}',
-        timestamp: '{{timestamp}}',
-        contentData: {
-            id: '{{content.id}}',
-            title: '{{content.title}}',
-            referenceName: '{{content.referenceName}}'
-        },
-        customField: 'custom value'
-    }
-};
-
-// Create webhook with signature verification
-const secureWebhook = {
-    name: 'Secure Webhook',
-    url: 'https://api.example.com/webhooks/secure',
-    events: ['content.created', 'content.updated'],
-    isActive: true,
-    method: 'POST',
-    contentType: 'application/json',
-    timeout: 30000,
-    retryCount: 3,
-    authentication: {
-        type: 'signature',
-        secret: 'your-webhook-secret',
-        algorithm: 'sha256',
-        headerName: 'X-Agility-Signature'
-    }
-};
-
-// Bulk webhook operations
-const createContentWebhooks = async (endpoints) => {
-    const webhooks = [];
-    for (const endpoint of endpoints) {
-        const webhook = {
-            name: `Content Webhook - ${endpoint.name}`,
-            url: endpoint.url,
-            events: ['content.created', 'content.updated', 'content.published'],
-            isActive: true,
-            method: 'POST',
-            contentType: 'application/json',
-            timeout: 30000,
-            retryCount: 3
-        };
-        
-        const saved = await apiClient.webhookMethods.saveWebhook(webhook, guid);
-        webhooks.push(saved);
-    }
-    return webhooks;
-};
+const webhook = new Webhook();
+webhook.name = 'Content Publish Notification';
+webhook.url = 'https://api.example.com/webhooks/agility';
+webhook.enabled = true;
+webhook.contentSaveEvents = false;
+webhook.contentPublishEvents = true;
+webhook.contentWorkflowEvents = false;
+webhook.retriesEnabled = true;
+webhook.retryCount = 5;
+webhook.retrySpeed = 'standard';
+
+const saved = await apiClient.webhookMethods.saveWebhook(guid, webhook);
+console.log('Webhook created with ID:', saved.rowKey);
+
+// Update an existing webhook (partitionKey/rowKey carry through from the get)
+const existing = await apiClient.webhookMethods.getWebhook(guid, saved.rowKey);
+existing.name = 'Updated Webhook Name';
+existing.contentWorkflowEvents = true;
+
+const updated = await apiClient.webhookMethods.saveWebhook(guid, existing);
+console.log('Webhook updated:', updated.name);
 ```
 
-**Webhook Structure:**
+**Error Handling:**
+- Throws `Exception` when validation or the save operation fails
+
+### deleteWebhook
+
+Deletes a webhook by its ID. Deletion immediately stops future deliveries for that webhook, and also removes that webhook's delivery history — history is keyed by webhook, so it is not retrievable once the webhook is gone. Export anything you need first.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | `string` | Yes | Current website GUID |
+| `webhookID` | `string` | Yes | The webhook ID (`rowKey`) to delete |
+
+**Returns:** `void`
+
+**Usage Example:**
 ```typescript
-interface Webhook {
-    webhookID?: number;           // Auto-generated for new webhooks
-    name: string;                 // Human-readable name (required)
-    url: string;                  // Target URL (required)
-    events: string[];             // Array of event types (required)
-    isActive: boolean;            // Whether webhook is active
-    method: string;               // HTTP method (GET, POST, PUT, etc.)
-    contentType: string;          // Content type for payload
-    timeout: number;              // Request timeout in milliseconds
-    retryCount: number;           // Number of retry attempts
-    authentication?: WebhookAuth; // Authentication configuration
-    payloadTemplate?: any;        // Custom payload template
-    statistics?: WebhookStats;    // Delivery statistics (read-only)
-    createdDate?: string;         // Auto-generated
-    lastTriggered?: string;       // Auto-generated
-}
+await apiClient.webhookMethods.deleteWebhook(guid, webhookID);
+console.log('Webhook deleted');
+```
 
-interface WebhookAuth {
-    type: string;                 // 'header', 'signature', 'basic', etc.
-    headers?: { [key: string]: string }; // Custom headers
-    secret?: string;              // Secret for signature authentication
-    algorithm?: string;           // Algorithm for signature (sha256, etc.)
-    headerName?: string;          // Header name for signature
-}
+**Error Handling:**
+- Throws `Exception` when the webhook is not found or deletion fails
+
+### getWebhookHistory
 
-interface WebhookStats {
-    totalDeliveries: number;      // Total delivery attempts
-    successfulDeliveries: number; // Successful deliveries
-    failedDeliveries: number;     // Failed deliveries
-    successRate: number;          // Success rate percentage
-    lastDeliveryDate: string;     // Last delivery attempt date
-    lastSuccessDate: string;      // Last successful delivery date
+Retrieves the delivery history for a webhook — one record per event delivery, including the payload, HTTP response, and retry state. Requires *Manage* permission on webhooks.
+
+Dates are UTC dates. The date range may span at most **366 days**; when no range is given, the **last 7 days** are returned. `take` is capped at **100** per page; use the continuation `token` for more.
+
+Records come back **newest first**, and that ordering holds *across* pages — history is stored newest-first, so paging walks it in order rather than sorting each page in isolation. Treat `token` as opaque: it identifies a position in the sequence and is only meaningful for the same `webhookID` and date range.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | `string` | Yes | Current website GUID |
+| `webhookID` | `string` | Yes | The webhook ID (`rowKey`) whose history to retrieve |
+| `options` | `object` | No | Optional query options (below) |
+| `options.fromDate` | `string` | No | UTC start date (e.g. `2026-08-01`) |
+| `options.toDate` | `string` | No | UTC end date; range max 366 days |
+| `options.take` | `number` | No | Records per page, max 100 |
+| `options.token` | `string` | No | Continuation token from a previous response |
+
+**Returns:** `TokenPagedResult<WebhookHistory>` - `{ token, items }` with the continuation token and the history records
+
+**Usage Example:**
+```typescript
+// Last 7 days (default)
+const history = await apiClient.webhookMethods.getWebhookHistory(guid, webhookID);
+history.items.forEach(entry => {
+    console.log(`${entry.sendDate} -> HTTP ${entry.httpResponseCode} (success: ${entry.success})`);
+    if (!entry.success) {
+        console.log(`  attempts: ${entry.attemptCount}, next attempt: ${entry.nextAttemptUtc}`);
+        console.log(`  last error: ${entry.lastError}`);
+    }
+});
+
+// A specific window, paging through all records
+let page = await apiClient.webhookMethods.getWebhookHistory(guid, webhookID, {
+    fromDate: '2026-08-01',
+    toDate: '2026-08-15',
+    take: 100
+});
+const failures = page.items.filter(e => !e.success);
+while (page.token) {
+    page = await apiClient.webhookMethods.getWebhookHistory(guid, webhookID, {
+        fromDate: '2026-08-01',
+        toDate: '2026-08-15',
+        take: 100,
+        token: page.token
+    });
+    failures.push(...page.items.filter(e => !e.success));
 }
+console.log(`Failed deliveries in window: ${failures.length}`);
 ```
 
-**Authentication Types:**
-- `header`: Custom headers for authentication
-- `signature`: HMAC signature verification
-- `basic`: Basic authentication
-- `bearer`: Bearer token authentication
-- `custom`: Custom authentication scheme
+**WebhookHistory Properties:**
+- `partitionKey` / `rowKey`: Storage identity of the history record. **`rowKey` is the value sent as the `webhook-id` header**, so use it to correlate a history record with what your endpoint received. Both are opaque — treat them as strings and don't parse them; the internal format is not part of this contract
+- `webhookRowKey`: The ID of the webhook this delivery belongs to
+- `eventKey`: Identifier of the triggering *event*, shared by every webhook that received it (used server-side for de-duplication). This is **not** the `webhook-id` header — correlate with `rowKey` instead
+- `queuedDate` / `sendDate`: When the delivery was queued and sent
+- `url`: The URL the payload was POSTed to
+- `instanceGuid`: The instance the event originated from
+- `contentSaveEvent` / `contentPublishEvent` / `contentWorkflowEvent`: Which event category fired
+- `payload`: The JSON payload that was sent
+- `httpResponseCode` / `success` / `responseText`: The endpoint's response (any 2xx counts as success)
+- `attemptCount` / `lastAttemptDate` / `nextAttemptUtc` / `lastError`: Retry state for failed deliveries. `attemptCount > 1` means the record is a retry; a failed record with no `nextAttemptUtc` will not be attempted again
+- `signed` / `signatureKeyCount`: Whether the last attempt went out with signature headers, and how many signatures it carried (0 unsigned, 1 normally, 2 inside the 24-hour window after a secret roll). Recorded at send time, so it reports what *that* delivery did — it is not the webhook's current `secureDeliveryEnabled`, which can change at any time. `signed` is `null` when there is no record: the delivery has not been attempted yet, or the record predates the field
 
 **Error Handling:**
-- Throws `Exception` when validation fails (invalid URL, unsupported events, etc.)
-- Throws `Exception` when save operation fails
-- Throws `Exception` when authentication configuration is invalid
+- Throws `Exception` when retrieval fails (including insufficient permissions or an invalid date range)
 
-### deleteWebhook
+### rotateWebhookSecret
+
+Rotates the webhook's signing secret. Requires *FullControl* permission on webhooks.
 
-Deletes a webhook by its ID.
+The response is the only place the new secret is returned in full — store it immediately. The previous secret is kept as `previousSigningSecret` so deliveries signed during the rollover window can still be verified; update your endpoint to the new secret promptly.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `webhookID` | `number` | Yes | The webhook ID to delete |
 | `guid` | `string` | Yes | Current website GUID |
+| `webhookID` | `string` | Yes | The webhook ID (`rowKey`) whose secret to rotate |
 
-**Returns:** `string` - Confirmation message of successful deletion
+**Returns:** `Webhook` - The webhook with the new, unmasked `signingSecret`, the old secret in `previousSigningSecret`, and `secretRolledUtc` set to the rotation time
 
 **Usage Example:**
 ```typescript
-try {
-    const result = await apiClient.webhookMethods.deleteWebhook(123, guid);
-    console.log(result); // "Webhook deleted successfully"
-} catch (error) {
-    console.error('Failed to delete webhook:', error.message);
+const rotated = await apiClient.webhookMethods.rotateWebhookSecret(guid, webhookID);
+console.log('New signing secret:', rotated.signingSecret); // whsec_...
+console.log('Rotated at:', rotated.secretRolledUtc);
+
+// Store the new secret in your secret manager, then update your endpoint's verifier.
+```
+
+**Error Handling:**
+- Throws `Exception` when rotation fails (including insufficient permissions)
+
+---
+
+## The Webhook object
+
+```typescript
+class Webhook {
+    partitionKey: string | null;      // Storage identity — required (with rowKey) to update an existing webhook
+    rowKey: string | null;            // The webhook's ID (GUID); used as webhookID in the other methods
+    timestamp?: string | null;        // Storage timestamp (read-only)
+    eTag?: string | null;             // Storage ETag (read-only)
+    name: string | null;              // Human-readable name
+    url: string | null;               // Target URL for deliveries
+    instanceGuid: string | null;      // Instance the webhook belongs to
+    enabled: boolean;                 // Whether the webhook fires at all
+    contentWorkflowEvents: boolean;   // Fire on workflow events (request approval, approve, decline)
+    contentPublishEvents: boolean;    // Fire on publish/unpublish events
+    contentSaveEvents: boolean;       // Fire on save/delete events
+    secureDeliveryEnabled: boolean;   // Opt-in for signed delivery (default false; existing webhooks stay unsigned)
+    signingSecret: string | null;     // Standard Webhooks secret (whsec_...) — server-controlled, masked without FullControl permission
+    previousSigningSecret: string | null; // Prior secret, kept for the rotation rollover window
+    secretRolledUtc: string | null;   // When the secret was last rotated
+    retriesEnabled: boolean;          // Whether failed deliveries are retried
+    retryCount: number;               // Retries after the initial attempt (1-8)
+    retrySpeed: "fast" | "standard" | "slow" | null; // Base retry delay tier
 }
+```
+
+## Verifying deliveries (signing)
+
+Deliveries for a webhook with `secureDeliveryEnabled: true` are signed per the [Standard Webhooks](https://www.standardwebhooks.com/) specification; those carry three extra headers. Deliveries for webhooks without it carry no signature headers at all, so verify signatures only for endpoints you have enabled secure delivery on:
+
+| Header | Description |
+|--------|-------------|
+| `webhook-id` | Unique ID of this delivery (the history record's `rowKey`) — reuse it as an **idempotency key**, since retries resend the same `webhook-id` |
+| `webhook-timestamp` | Unix timestamp (seconds) of the delivery attempt |
+| `webhook-signature` | `v1,<base64 signature>` — HMAC-SHA256 over `{id}.{timestamp}.{body}` keyed with the decoded secret |
 
-// Safe webhook deletion with confirmation
-const safeDeleteWebhook = async (webhookID) => {
+The signing secret is the webhook's `signingSecret` (`whsec_` followed by the base64-encoded key). Verify with any Standard Webhooks library rather than hand-rolling the HMAC:
+
+```typescript
+import { Webhook as StandardWebhook } from 'standardwebhooks';
+
+const verifier = new StandardWebhook(process.env.AGILITY_WEBHOOK_SECRET); // whsec_...
+
+app.post('/webhooks/agility', (req, res) => {
     try {
-        // Get webhook details first
-        const webhook = await apiClient.webhookMethods.getWebhook(webhookID, guid);
-        console.log(`About to delete webhook: ${webhook.name}`);
-        console.log(`URL: ${webhook.url}`);
-        console.log(`Events: ${webhook.events.join(', ')}`);
-        
-        // Check if webhook is active
-        if (webhook.isActive) {
-            console.log('Warning: Deleting active webhook');
-        }
-        
-        // Perform deletion
-        const result = await apiClient.webhookMethods.deleteWebhook(webhookID, guid);
-        console.log('Webhook deleted successfully');
-        return result;
-    } catch (error) {
-        console.error('Failed to delete webhook:', error.message);
-        throw error;
-    }
-};
-
-// Bulk cleanup of inactive webhooks
-const cleanupInactiveWebhooks = async () => {
-    const webhooks = await apiClient.webhookMethods.getWebhookList(guid);
-    const inactiveWebhooks = webhooks.filter(w => !w.isActive);
-    
-    console.log(`Found ${inactiveWebhooks.length} inactive webhooks`);
-    
-    for (const webhook of inactiveWebhooks) {
-        const shouldDelete = confirm(
-            `Delete inactive webhook "${webhook.name}"? (${webhook.url})`
-        );
-        
-        if (shouldDelete) {
-            await apiClient.webhookMethods.deleteWebhook(webhook.webhookID, guid);
-            console.log(`Deleted webhook: ${webhook.name}`);
-        }
-    }
-};
-
-// Delete webhooks with high failure rates
-const cleanupFailingWebhooks = async (maxFailureRate = 50) => {
-    const webhooks = await apiClient.webhookMethods.getWebhookList(guid);
-    
-    const failingWebhooks = webhooks.filter(webhook => 
-        webhook.statistics && 
-        webhook.statistics.successRate < maxFailureRate &&
-        webhook.statistics.totalDeliveries > 10 // Only consider webhooks with sufficient data
-    );
-    
-    console.log(`Found ${failingWebhooks.length} webhooks with high failure rate`);
-    
-    for (const webhook of failingWebhooks) {
-        console.log(`Webhook "${webhook.name}" has ${webhook.statistics.successRate}% success rate`);
-        
-        const shouldDelete = confirm(
-            `Delete failing webhook "${webhook.name}"? (Success rate: ${webhook.statistics.successRate}%)`
-        );
-        
-        if (shouldDelete) {
-            await apiClient.webhookMethods.deleteWebhook(webhook.webhookID, guid);
-            console.log(`Deleted failing webhook: ${webhook.name}`);
+        // verify() checks the signature AND enforces the timestamp tolerance
+        const payload = verifier.verify(req.rawBody, req.headers);
+
+        // Use webhook-id for idempotency — retries resend the same id
+        if (alreadyProcessed(req.headers['webhook-id'])) {
+            return res.sendStatus(200);
         }
+
+        processEvent(payload);
+        res.sendStatus(200); // any 2xx marks the delivery successful
+    } catch {
+        res.sendStatus(401);
     }
-};
+});
 ```
 
-**Deletion Considerations:**
-- Deleting a webhook immediately stops all future event deliveries
-- Pending webhook deliveries may still be processed
-- Webhook statistics and history are permanently lost
-- Consider deactivating instead of deleting for temporary suspension
-
-**Best Practices:**
-- Test webhook endpoints before creating webhooks
-- Use appropriate authentication to secure webhook endpoints
-- Monitor webhook statistics and success rates
-- Implement proper error handling in webhook receivers
-- Use webhook signatures to verify authenticity
-- Set reasonable timeout values to avoid blocking
-- Consider implementing idempotency in webhook receivers
+**Verification rules:**
+- Reject deliveries whose `webhook-timestamp` is more than **5 minutes** from now (standard libraries enforce this) — this bounds replay attacks
+- During a secret rotation, accept signatures from either the new secret or `previousSigningSecret`
+- Respond with a **2xx** status to acknowledge; anything else (or a timeout) counts as a failure and triggers retries when enabled
 
-**Error Handling:**
-- Throws `Exception` when webhook not found
-- Throws `Exception` when deletion fails
-- Throws `Exception` when insufficient permissions to delete webhooks
+## Retry behavior
+
+Retries apply per delivery and are configured on the webhook:
+
+- `retriesEnabled` — master switch; when false, one attempt is made and failures are recorded but never retried
+- `retryCount` — how many retries are made **after the initial attempt**, from 1 to 8
+- `retrySpeed` — the base delay before the first retry:
+
+| Speed | Base delay |
+|-------|-----------|
+| `fast` | 30 seconds |
+| `standard` | 5 minutes |
+| `slow` | 30 minutes |
+
+Each subsequent retry backs off exponentially at **×4** the previous delay, with jitter, capped at **24 hours** between attempts. For example, `standard` retries land at roughly 5m, 20m, 80m, ... after the failure.
+
+A delivery is successful as soon as the endpoint returns any **2xx** response; success stops the retry chain. Retry state for a delivery is visible in [getWebhookHistory](#getwebhookhistory) via `attemptCount`, `lastAttemptDate`, `nextAttemptUtc`, and `lastError`.
 
 ---
 
@@ -448,5 +348,4 @@ const cleanupFailingWebhooks = async (maxFailureRate = 50) => {
 - [ModelMethods](./model-methods.md)
 - [PageMethods](./page-methods.md)
 - [ServerUserMethods](./server-user-methods.md)
-- [ServerUserMethods](./server-user-methods.md)
-- **WebhookMethods** *(current)* 
+- **WebhookMethods** *(current)*