> ## Documentation Index > Fetch the complete documentation index at: https://docs.nvisy.com/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook > Creates a new webhook for the workspace. The response includes the signing secret which is used for HMAC-SHA256 verification of webhook payloads. **Important**: The secret is only shown once upon creation and cannot be retrieved again. ## OpenAPI ````yaml /api-reference/openapi.json post /workspaces/{workspaceSlug}/webhooks/ openapi: 3.1.0 info: title: Nvisy API summary: Document processing and annotation platform description: >- Nvisy provides intelligent document processing, annotation, and analysis capabilities. This API enables document upload, OCR processing, embedding generation, and semantic search across your document collections. termsOfService: https://nvisy.com/legal/terms-of-service contact: name: Nvisy Support url: https://nvisy.com email: hello@nvisy.com license: name: Proprietary url: https://nvisy.com/license version: 0.1.0 servers: [] security: [] tags: - name: Accounts description: Account management and profile operations - name: Authentication description: Login, signup, and token management - name: Workspaces description: Workspace creation and management - name: Files description: File upload, download, and management - name: Members description: Workspace member management - name: Invites description: Workspace invitation handling - name: API Tokens description: API token management - name: Connections description: External provider connections - name: Pipelines description: Redaction pipeline configuration - name: Pipeline Runs description: Pipeline run execution and review - name: Policies description: Redaction policy configuration - name: Webhooks description: Webhook configuration - name: Notifications description: Account notification management - name: Health description: Service health checks paths: /workspaces/{workspaceSlug}/webhooks/: post: tags: - Webhooks summary: Create webhook description: >- Creates a new webhook for the workspace. The response includes the signing secret which is used for HMAC-SHA256 verification of webhook payloads. **Important**: The secret is only shown once upon creation and cannot be retrieved again. parameters: - in: path name: workspaceSlug description: URL-safe workspace identifier. required: true schema: description: URL-safe workspace identifier. type: string style: simple requestBody: description: Request payload for creating a new workspace webhook. content: application/json: schema: $ref: '#/components/schemas/CreateWebhook' required: true responses: '201': description: >- Webhook creation response that includes the secret (visible only once). The secret is used for HMAC-SHA256 signature verification of webhook payloads. It is only returned when the webhook is first created and cannot be retrieved again. Store it securely. content: application/json: schema: $ref: '#/components/schemas/WebhookCreated' '400': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: 'Expected request with `Content-Type: application/json`' content: text/plain: schema: type: string '422': description: Failed to deserialize the JSON body into the target type content: text/plain: schema: type: string security: - BearerAuth: [] components: schemas: CreateWebhook: description: Request payload for creating a new workspace webhook. type: object properties: description: description: Detailed description of the webhook's purpose (max 500 characters). type: string maxLength: 500 displayName: description: Human-readable name for the webhook (1-128 characters). type: string maxLength: 128 minLength: 1 events: description: List of event types this webhook should receive. type: array items: $ref: '#/components/schemas/WebhookEvent' headers: description: Optional custom headers to include in webhook requests. type: object additionalProperties: type: string status: $ref: '#/components/schemas/WebhookStatus' description: Initial status of the webhook (enabled or disabled). url: description: The URL to send webhook payloads to. type: string format: uri maxLength: 2048 required: - displayName - description - url - events WebhookCreated: description: >- Webhook creation response that includes the secret (visible only once). The secret is used for HMAC-SHA256 signature verification of webhook payloads. It is only returned when the webhook is first created and cannot be retrieved again. Store it securely. type: object properties: consecutiveFailures: description: Consecutive failed deliveries since the last success. type: integer format: int32 createdAt: description: Timestamp when this webhook was first created. type: string format: date-time createdBy: description: Account that created this webhook. allOf: - $ref: '#/components/schemas/AccountRef' description: description: Detailed description of the webhook's purpose. type: string displayName: description: Human-readable name for the webhook. type: string events: description: List of event types this webhook receives. type: array items: $ref: '#/components/schemas/WebhookEvent' headers: description: Custom headers included in webhook requests. type: object additionalProperties: type: string id: description: Opaque identifier of the webhook. allOf: - $ref: '#/components/schemas/WebhookId' lastFailureAt: description: Timestamp of the most recent failed delivery. type: string format: date-time lastSuccessAt: description: Timestamp of the most recent successful delivery. type: string format: date-time secret: description: |- HMAC-SHA256 signing secret for webhook verification. **Important**: This is the only time the secret will be shown. Store it securely as it cannot be retrieved again. type: string status: description: Current status of the webhook. allOf: - $ref: '#/components/schemas/WebhookStatus' updatedAt: description: Timestamp when this webhook was last modified. type: string format: date-time url: description: The URL to send webhook payloads to. type: string workspaceSlug: description: Handle of the workspace this webhook belongs to. allOf: - $ref: '#/components/schemas/Handle' required: - id - workspaceSlug - displayName - description - url - events - headers - status - consecutiveFailures - createdBy - createdAt - updatedAt - secret ErrorResponse: description: |- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. type: object properties: message: description: User-friendly error message safe for client display type: string name: description: The error name/type identifier type: string resource: description: The resource that the error relates to (optional, set by handler) type: string suggestion: description: Helpful suggestion for resolving the error (optional) type: string validation: description: Validation error details for field-specific errors type: array items: $ref: '#/components/schemas/ValidationErrorDetail' required: - name - message WebhookEvent: description: >- Defines the types of events that can trigger webhook delivery. This enumeration corresponds to the `WEBHOOK_EVENT` PostgreSQL enum and is used to configure which events a webhook should receive notifications for. oneOf: - description: A new file was created type: string const: file.created - description: A file was updated type: string const: file.updated - description: A file was deleted type: string const: file.deleted - description: A member was added to the workspace type: string const: member.added - description: A member was deleted from the workspace type: string const: member.deleted - description: A member's details were updated type: string const: member.updated - description: A connection was created type: string const: connection.created - description: A connection was updated type: string const: connection.updated - description: A connection was deleted type: string const: connection.deleted - description: A connection sync started type: string const: connection.sync.started - description: A connection sync finished successfully type: string const: connection.sync.completed - description: A connection sync failed type: string const: connection.sync.failed - description: A pipeline was created type: string const: pipeline.created - description: A pipeline was updated type: string const: pipeline.updated - description: A pipeline was deleted type: string const: pipeline.deleted - description: A pipeline run started type: string const: pipeline.run.started - description: A pipeline run's detection finished (findings ready for review) type: string const: pipeline.run.analyzed - description: A pipeline run finished successfully type: string const: pipeline.run.completed - description: A pipeline run failed type: string const: pipeline.run.failed - description: A policy was created type: string const: policy.created - description: A policy was updated type: string const: policy.updated - description: A policy was deleted type: string const: policy.deleted WebhookStatus: description: >- Defines the operational status of a workspace webhook. This enumeration corresponds to the `WEBHOOK_STATUS` PostgreSQL enum. The user controls `Enabled` / `Disabled`; `Suspended` is set by the system when a webhook fails repeatedly, and the user can re-enable it. oneOf: - description: Webhook is enabled and will receive events. type: string const: enabled - description: Webhook was disabled by the user. type: string const: disabled - description: Webhook was suspended by the system (e.g., too many failures). type: string const: suspended AccountRef: description: >- Public reference to the account behind a resource — whoever created it, uploaded it, triggered it, or performed it. Reused across resource responses so an account is always presented the same way: a handle plus an optional avatar. type: object properties: avatarUrl: description: Serve path of the account's avatar, when set. type: string displayName: description: Human-readable display name, when set. type: string username: description: Handle of the account. allOf: - $ref: '#/components/schemas/Handle' required: - username WebhookId: description: Opaque whk identifier (whk_). type: string pattern: >- ^whk_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ Handle: description: >- Lowercase, dash-separated identifier used in URLs and as account handles. type: string maxLength: 32 minLength: 3 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ ValidationErrorDetail: description: Validation error details for field-specific errors. type: object properties: code: description: Error code for the validation failure type: string field: description: Field name that failed validation type: string message: description: Human-readable error message type: string params: description: Additional parameters related to the validation error type: object additionalProperties: true required: - field - code - message ````