Manage webhook subscriptions

Receive notifications at your own HTTPS endpoint after generation or Autopilot events. Use the account Bearer token for subscription management; outgoing deliveries use a separate webhook signing secret.

{
    "title": "List webhook subscriptions",
    "description": "",
    "method": "GET",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer YOUR_API_TOKEN",
            "type": "string",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "type": "string",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "success: true and data containing the account subscriptions, newest first. Illustrative JSON example; sample values are fictional. Some optional or additional resource fields may be omitted.",
            "body": "{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 789,\n      \"webhook_url\": \"https://example.com/hooks/docuwriter\",\n      \"events\": [\n        \"generation.created\"\n      ],\n      \"is_active\": true,\n      \"metadata\": {\n        \"integration\": \"docs-build\"\n      }\n    }\n  ]\n}"
        },
        "401": {
            "description": "Missing or invalid account API token.Missing or invalid account API token. Example JSON response.",
            "body": "{\n  \"message\": \"Unauthenticated.\"\n}"
        }
    }
}

{
    "title": "Create a webhook subscription",
    "description": "",
    "method": "POST",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer YOUR_API_TOKEN",
            "type": "string",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "type": "string",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "type": "string",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n  \"webhook_url\": \"https://example.com/hooks/docuwriter\",\n  \"events\": [\n    \"generation.created\"\n  ],\n  \"metadata\": {\n    \"integration\": \"docs-build\"\n  }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "success, message and data containing id, webhook_url, events, secret, is_active, metadata and timestamps. Store the returned signing secret securely. Illustrative JSON example; sample values are fictional. Some optional or additional resource fields may be omitted.",
            "body": "{\n  \"success\": true,\n  \"data\": {\n    \"id\": 789,\n    \"webhook_url\": \"https://example.com/hooks/docuwriter\",\n    \"events\": [\n      \"generation.created\"\n    ],\n    \"is_active\": true,\n    \"metadata\": {\n      \"integration\": \"docs-build\"\n    },\n    \"secret\": \"EXAMPLE_SIGNING_SECRET\"\n  },\n  \"message\": \"Webhook subscription created successfully\"\n}"
        },
        "401": {
            "description": "Missing or invalid account API token.Missing or invalid account API token. Example JSON response.",
            "body": "{\n  \"message\": \"Unauthenticated.\"\n}"
        }
    }
}

{
    "title": "Read a webhook subscription",
    "description": "",
    "method": "GET",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/{id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer YOUR_API_TOKEN",
            "type": "string",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "type": "string",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "value": "Numeric resource ID returned by this API.",
            "type": "integer",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "success: true and data containing the account-owned subscription. Illustrative JSON example; sample values are fictional. Some optional or additional resource fields may be omitted.",
            "body": "{\n  \"success\": true,\n  \"data\": {\n    \"id\": 789,\n    \"webhook_url\": \"https://example.com/hooks/docuwriter\",\n    \"events\": [\n      \"generation.created\"\n    ],\n    \"is_active\": true,\n    \"metadata\": {\n      \"integration\": \"docs-build\"\n    }\n  }\n}"
        },
        "401": {
            "description": "Missing or invalid account API token.Missing or invalid account API token. Example JSON response.",
            "body": "{\n  \"message\": \"Unauthenticated.\"\n}"
        },
        "404": {
            "description": "Subscription not found for this account.",
            "body": "{\n  \"success\": false,\n  \"message\": \"Webhook subscription not found\"\n}"
        }
    }
}

{
    "title": "Update a webhook subscription",
    "description": "",
    "method": "PUT",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/{id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer YOUR_API_TOKEN",
            "type": "string",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "type": "string",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "type": "string",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "value": "Numeric resource ID returned by this API.",
            "type": "integer",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n  \"is_active\": false\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "success, message and updated subscription under data. Optional fields: webhook_url, events, is_active, metadata. Illustrative JSON example; sample values are fictional. Some optional or additional resource fields may be omitted.",
            "body": "{\n  \"success\": true,\n  \"data\": {\n    \"id\": 789,\n    \"webhook_url\": \"https://example.com/hooks/docuwriter\",\n    \"events\": [\n      \"generation.created\"\n    ],\n    \"is_active\": false,\n    \"metadata\": {\n      \"integration\": \"docs-build\"\n    }\n  },\n  \"message\": \"Webhook subscription updated successfully\"\n}"
        },
        "401": {
            "description": "Missing or invalid account API token.Missing or invalid account API token. Example JSON response.",
            "body": "{\n  \"message\": \"Unauthenticated.\"\n}"
        },
        "404": {
            "description": "Subscription not found for this account.",
            "body": "{\n  \"success\": false,\n  \"message\": \"Webhook subscription not found\"\n}"
        }
    }
}

{
    "title": "Delete a webhook subscription",
    "description": "",
    "method": "DELETE",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/{id}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer YOUR_API_TOKEN",
            "type": "string",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "type": "string",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "value": "Numeric resource ID returned by this API.",
            "type": "integer",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "JSON success message; this endpoint does not return an empty 204 response. Illustrative JSON example; sample values are fictional. Some optional or additional resource fields may be omitted.",
            "body": "{\n  \"success\": true,\n  \"message\": \"Webhook subscription deleted successfully\"\n}"
        },
        "401": {
            "description": "Missing or invalid account API token.Missing or invalid account API token. Example JSON response.",
            "body": "{\n  \"message\": \"Unauthenticated.\"\n}"
        },
        "404": {
            "description": "Subscription not found for this account.",
            "body": "{\n  \"success\": false,\n  \"message\": \"Webhook subscription not found\"\n}"
        }
    }
}

{
    "title": "List available webhook events",
    "description": "",
    "method": "GET",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/events/available",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer YOUR_API_TOKEN",
            "type": "string",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "type": "string",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "success: true and data containing available event names and labels. Illustrative JSON example; sample values are fictional. Some optional or additional resource fields may be omitted.",
            "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}"
        },
        "401": {
            "description": "Missing or invalid account API token.Missing or invalid account API token. Example JSON response.",
            "body": "{\n  \"message\": \"Unauthenticated.\"\n}"
        }
    }
}

{
    "title": "Dispatch a webhook test",
    "description": "",
    "method": "POST",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/webhooks/{id}/test",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer YOUR_API_TOKEN",
            "type": "string",
            "required": true
        },
        {
            "key": "Accept",
            "value": "application/json",
            "type": "string",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "value": "Numeric resource ID returned by this API.",
            "type": "integer",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Dispatch acknowledgment; not proof of receiver delivery. Illustrative JSON example; sample values are fictional. Some optional or additional resource fields may be omitted.",
            "body": "{\n  \"success\": true,\n  \"message\": \"Test webhook dispatched successfully\"\n}"
        },
        "401": {
            "description": "Missing or invalid account API token.Missing or invalid account API token. Example JSON response.",
            "body": "{\n  \"message\": \"Unauthenticated.\"\n}"
        },
        "404": {
            "description": "Subscription not found for this account.",
            "body": "{\n  \"success\": false,\n  \"message\": \"Webhook subscription not found\"\n}"
        }
    }
}

Create a subscription

• webhook_url must be a public HTTPS URL.
• Loopback, private-network and unsafe destinations are rejected. events is a required non-empty array of exact supported names.
• Optional metadata is an object/array for your integration context.
• HTTP 201 returns success, message, and the subscription under data, including its id, webhook_url, events, secret, is_active, and metadata/timestamps.
• Store the secret securely for signature verification; do not publish or log the response wholesale.

Update and remove

• PUT accepts optional webhook_url, events, is_active and metadata.
• Set is_active: false to pause delivery without deleting the subscription.
• DELETE returns a JSON success message, not an empty 204.
• A missing subscription or one belonging to another account returns 404; invalid fields return 422.
• The test dispatch uses test.webhook; subscription creation accepts only names returned by the available-events endpoint.
• A dispatch acknowledgment does not prove delivery.
• Validate your integration with a real subscribed event and receiver logs.
• See Event payloads.

API authentication.