Webhooks & Security 🔒

DocuWriter.ai delivers an event-driven experience via webhooks. Clients register HTTP endpoints to receive real-time notifications for key actions. All webhook payloads carry an HMAC-SHA256 signature to ensure authenticity.

Security

Signature Verification: Each request includes an X-DocuWriter-Signature: sha256= header computed over the JSON body with the subscription's secret .
Event Header: X-DocuWriter-Event indicates the event name.
User-Agent: DocuWriter-Webhook/1.0 is set for all dispatches.

Supported Events 🎉

You can subscribe to:

Event Name	Description
`generation.created`	A new generation is created, such as documentation, tests, diagrams, or optimization.
`generation.updated`	An existing generation is modified.
`repository_sync.suggestions_ready`	Autopilot finishes analyzing repository changes and has documentation suggestions ready for review.
`repository_sync.suggestion_applied`	An Autopilot suggestion is approved and applied.
`repository_sync.suggestion_discarded`	An Autopilot suggestion is rejected.

Available event keys are also returned via the management API.

Event Payload Schema 📬

All webhook calls send a JSON body:

event (string): The event name.
timestamp (string, ISO 8601): When the event occurred.
webhook_id (integer): Subscription identifier.
data (object): Event-specific details.

data Fields for Documentation Events

Field	Type	Description
`id`	integer	Generation ID
`uuid`	string	Public UUID of the generation
`filename`	string	File name associated with the generation
`generation_type`	integer	Numeric public generation type identifier. For example, `0` represents code documentation.
`generated_by_user`	string or null	Email of the user who triggered the generation
`created_at` / `updated_at`	string (ISO 8601)	Timestamp of creation or update
`tag`	string or null	Optional user-supplied tag

data Fields for Repository Sync Events

Individual Suggestion Events (suggestion_applied, suggestion_discarded)

Field	Type	Description
`suggestion_id`	integer	Suggestion ID
`batch_id`	integer	Batch identifier containing this suggestion
`space_id`	integer	Documentation Space ID
`space_name`	string	Name of the documentation Space
`suggestion_type`	string	Type: `new_item` or `update`
`target_item`	object	Target documentation item information
`target_item.id`	integer or null	Target item ID (`null` for new items)
`target_item.name`	string	Target item title or name
`summary`	string	Summary of the suggestion
`suggested_markdown`	string	Suggested Markdown content
`original_markdown`	string or null	Original Markdown content (`null` for new items)
`applied_by` / `discarded_by`	object	User who performed the action
`applied_by.id` / `discarded_by.id`	integer	User ID
`applied_by.email` / `discarded_by.email`	string	User email
`applied_at` / `discarded_at`	string (ISO 8601)	Timestamp when the action occurred
`repository`	object	Repository information
`repository.provider`	string	Git provider: `github`, `gitlab`, `bitbucket`, or `azure` (Azure DevOps)
`repository.identifier`	string	Repository identifier, such as `owner/repo`
`repository.branch`	string	Branch name
`repository.commit_sha`	string	Commit SHA
`repository.pr_number`	integer or null	Pull request number, when applicable

Batch Ready Event (suggestions_ready)

Field	Type	Description
`batch_id`	integer	Batch identifier
`space_id`	integer	Documentation Space ID
`space_name`	string	Name of the documentation Space
`title`	string	Batch title
`suggestions_count`	integer	Number of suggestions in the batch
`suggestions`	array	Suggestion details
`suggestions[].id`	integer	Suggestion ID
`suggestions[].type`	string	Type: `new_item` or `update`
`suggestions[].target_name`	string	Target item name
`suggestions[].summary`	string	Suggestion summary
`suggestions[].suggested_markdown`	string	Suggested Markdown content
`suggestions[].original_markdown`	string or null	Original Markdown content (`null` for new items)
`repository`	object	Repository information using the structure above
`review_url`	string	URL to review the suggestions in DocuWriter

Example Payloads

Generation Created

{
  "event": "generation.created",
  "timestamp": "2025-01-08T10:30:14Z",
  "webhook_id": 123,
  "data": {
    "id": 456,
    "uuid": "89683484-f946-4184-98f9-9d89a0e9f26b",
    "filename": "vite.config.js",
    "generation_type": 0,
    "generated_by_user": "[email protected]",
    "created_at": "2025-01-08T10:30:14Z",
    "tag": null
  }
}

Repository Sync Suggestions Ready

{
  "event": "repository_sync.suggestions_ready",
  "timestamp": "2025-01-13T15:42:30Z",
  "webhook_id": 123,
  "data": {
    "batch_id": 789,
    "space_id": 456,
    "space_name": "My API Documentation",
    "title": "GitHub push on main: 2 files changed",
    "suggestions_count": 2,
    "suggestions": [
      {
        "id": 1024,
        "type": "new_item",
        "target_name": "Authentication API",
        "summary": "Add documentation for new OAuth2 endpoints",
        "suggested_markdown": "# Authentication API\n\nThis endpoint handles OAuth2 authentication...",
        "original_markdown": null
      },
      {
        "id": 1025,
        "type": "update",
        "target_name": "User Management",
        "summary": "Update user creation endpoint documentation",
        "suggested_markdown": "# User Management\n\nUpdated documentation with new field validation...",
        "original_markdown": "# User Management\n\nOld documentation text..."
      }
    ],
    "repository": {
      "provider": "github",
      "identifier": "acme-corp/api-server",
      "branch": "main",
      "commit_sha": "abc123def456",
      "commit_range": "abc123...def456",
      "pr_number": null
    },
    "review_url": "https://app.docuwriter.ai/space/456/autopilot/batch/789"
  }
}

Repository Sync Suggestion Applied

{
  "event": "repository_sync.suggestion_applied",
  "timestamp": "2025-01-13T16:15:22Z",
  "webhook_id": 123,
  "data": {
    "suggestion_id": 1024,
    "batch_id": 789,
    "space_id": 456,
    "space_name": "My API Documentation",
    "suggestion_type": "new_item",
    "target_item": {
      "id": 5432,
      "name": "Authentication API"
    },
    "summary": "Add documentation for new OAuth2 endpoints",
    "suggested_markdown": "# Authentication API\n\nThis endpoint handles OAuth2 authentication...",
    "original_markdown": null,
    "applied_by": {
      "id": 101,
      "email": "[email protected]"
    },
    "applied_at": "2025-01-13T16:15:22Z",
    "repository": {
      "provider": "github",
      "identifier": "acme-corp/api-server",
      "branch": "main",
      "commit_sha": "abc123def456",
      "pr_number": null
    }
  }
}

Repository Sync Suggestion Discarded

{
  "event": "repository_sync.suggestion_discarded",
  "timestamp": "2025-01-13T16:18:45Z",
  "webhook_id": 123,
  "data": {
    "suggestion_id": 1025,
    "batch_id": 789,
    "space_id": 456,
    "space_name": "My API Documentation",
    "suggestion_type": "update",
    "target_item": {
      "id": 5433,
      "name": "User Management"
    },
    "summary": "Update user creation endpoint documentation",
    "suggested_markdown": "# User Management\n\nUpdated documentation with new field validation...",
    "original_markdown": "# User Management\n\nOld documentation text...",
    "discarded_by": {
      "id": 101,
      "email": "[email protected]"
    },
    "discarded_at": "2025-01-13T16:18:45Z",
    "repository": {
      "provider": "github",
      "identifier": "acme-corp/api-server",
      "branch": "main",
      "commit_sha": "abc123def456",
      "pr_number": null
    }
  }
}

(examples formatted for clarity)

Logging

All dispatch attempts are recorded capturing:

webhook_subscription_id, event_type, payload
status_code, response_body, error_message
sent_at, response_time_ms

Management API Endpoints 🔧

Base URL: https://app.docuwriter.ai/api/webhooks

{
    "title": "List Webhook Subscriptions",
    "description": "Retrieve all webhook subscriptions for the authenticated user.",
    "method": "GET",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "OK",
            "body": "{\n  \"success\": true,\n  \"data\": [\n    { \"id\": 1, \"webhook_url\": \"...\", \"events\": [\"generation.created\"] }\n  ]\n}"
        }
    }
}

{
    "title": "Create Webhook Subscription",
    "description": "Register a new webhook URL for specified events.",
    "method": "POST",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n  \"webhook_url\": \"https://example.com/webhook\",\n  \"events\": [\"generation.created\"],\n  \"metadata\": { }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Created",
            "body": "{\n  \"success\": true,\n  \"data\": { \"id\": 2, \"secret\": \"<secret>\" },\n  \"message\": \"Webhook subscription created successfully\"\n}"
        },
        "422": {
            "description": "Validation Error",
            "body": "{ \"errors\": { \"events\": [\"Required\"] } }"
        }
    }
}

{
    "title": "Show Webhook Subscription",
    "description": "Get details of a specific webhook subscription.",
    "method": "GET",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/{id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "value": "Subscription ID",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "OK",
            "body": "{\n  \"success\": true,\n  \"data\": { \"id\": 2, \"webhook_url\": \"...\" }\n}"
        },
        "404": {
            "description": "Not Found",
            "body": "{ \"message\": \"Subscription not found\" }"
        }
    }
}

{
    "title": "Update Webhook Subscription",
    "description": "Modify URL, events, or activation status of a subscription.",
    "method": "PUT",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/{id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "value": "Subscription ID",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n  \"webhook_url\": \"https://new-url.com/hook\",\n  \"events\": [\"generation.updated\"],\n  \"is_active\": false\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "OK",
            "body": "{\n  \"success\": true,\n  \"data\": { \"id\": 2, \"is_active\": false },\n  \"message\": \"Webhook subscription updated successfully\"\n}"
        },
        "404": {
            "description": "Not Found",
            "body": "{ \"message\": \"Subscription not found\" }"
        }
    }
}

{
    "title": "Delete Webhook Subscription",
    "description": "Remove a webhook subscription.",
    "method": "DELETE",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/{id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "value": "Subscription ID",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Deleted",
            "body": "{ \"success\": true }"
        },
        "404": {
            "description": "Not Found",
            "body": "{ \"success\": false, \"message\": \"Webhook subscription not found\" }"
        }
    }
}

{
    "title": "Available Events",
    "description": "List all event names that can be subscribed to.",
    "method": "GET",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/events/available",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "OK",
            "body": "{\n  \"success\": true,\n  \"data\": {\n    \"generation.created\": \"Generation Created\",\n    \"generation.updated\": \"Generation Updated\",\n    \"repository_sync.suggestions_ready\": \"Autopilot Suggestions Ready\",\n    \"repository_sync.suggestion_applied\": \"Autopilot Suggestion Applied\",\n    \"repository_sync.suggestion_discarded\": \"Autopilot Suggestion Discarded\"\n  }\n}"
        }
    }
}

By following these specifications, integrators can securely subscribe, receive, verify, and manage webhook events in DocuWriter.ai.

Search this space