Visier Webhooks API

openapi: 3.2.0
info:
  title: Visier Webhooks API
  description: Visier APIs for managing your webhook integrations.
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 22222222.99201.3040
security:
- ApiKeyAuth: []
  BearerAuth: []
- ApiKeyAuth: []
  CookieAuth: []
- ApiKeyAuth: []
  OAuth2Auth: []
tags:
- name: Webhooks
  x-displayName: Webhooks
  description: Create, manage, and retrieve webhook definitions. Use webhooks to register your own HTTPS endpoints with Visier and listen for specific events. When these events occur, Visier sends an API request to your registered endpoint. For example, you can create a webhook to monitor job status events with Visier. Visier sends you a success or failure notification to your registered endpoint after the job completes.
paths:
  /v1/op/webhooks:
    get:
      tags:
      - Webhooks
      summary: Retrieve a list of webhooks
      description: Retrieve a list of all webhooks. The response returns each webhook's definition, such as its endpoint URL, active status, and event types.
      operationId: Webhooks_GetAllWebhooks
      parameters:
      - name: event
        in: query
        description: "Retrieve all webhooks listening for the specified event type. Default is to retrieve all webhooks.\n\n The possible event types to listen for. Valid values:\n - `jobResultSuccess`: A job completed successfully.\n - `jobResultFailure`: A job failed to complete.\n - `jobReschedule`: A job was rescheduled.\n - `dvPublish`: A data version published to production.\n - `alertNotification`: A personalized alert notification was triggered.\n - `smartCompNotification`: A Smart Compensation event notification was triggered. This is available for Embedded Partners.\n - `dataUploadNotification`: A data file was uploaded.\n - `systemAlertNotification`: A system event alert notification was triggered.\n - `planRowPromotionNotification`: A row in a plan was promoted.\n - `auditEvent`: An audit event was triggered."
        schema:
          type: string
      - name: isActive
        in: query
        description: If `true`, retrieve active webhooks only. If `false`, retrieve active and inactive webhooks. Default is `false`.
        schema:
          type: boolean
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhooksDTO'
    post:
      tags:
      - Webhooks
      summary: Create a webhook
      description: Create a new webhook with Visier. You must specify the webhook's endpoint URL, its active status, the event types to listen for, and the credentials to authenticate calls to the webhook endpoint.
      operationId: Webhooks_CreateWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/designer.webhook.WebhookRequestDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhookDTO'
  /v1/op/webhooks-status:
    get:
      tags:
      - Webhooks
      summary: Retrieve webhook statuses
      description: Retrieve the statuses of all webhooks, such as their active status and the event types they're listening for. API users can call this endpoint without any special capabilities.
      operationId: Webhooks_GetWebhooksStatus
      parameters:
      - name: event
        in: query
        description: "Retrieve all webhooks listening for the specified event type. Default is to retrieve all webhooks.\n\n The possible event types to listen for. Valid values:\n - `jobResultSuccess`: A job completed successfully.\n - `jobResultFailure`: A job failed to complete.\n - `jobReschedule`: A job was rescheduled.\n - `dvPublish`: A data version published to production.\n - `alertNotification`: A personalized alert notification was triggered.\n - `smartCompNotification`: A Smart Compensation event notification was triggered. This is available for Embedded Partners.\n - `dataUploadNotification`: A data file was uploaded.\n - `systemAlertNotification`: A system event alert notification was triggered.\n - `planRowPromotionNotification`: A row in a plan was promoted.\n - `auditEvent`: An audit event was triggered."
        schema:
          type: string
      - name: isActive
        in: query
        description: If `true`, retrieve active webhooks only. If `false`, retrieve active and inactive webhooks. Default is `false`.
        schema:
          type: boolean
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhookStatusesDTO'
  /v1/op/webhooks/{webhookId}:
    get:
      tags:
      - Webhooks
      summary: Retrieve a webhook's details
      description: Retrieve the details of a specific webhook. You must know the ID of the webhook to retrieve its details. To retrieve webhook IDs, see `GET /v1/op/webhooks`.
      operationId: Webhooks_GetWebhook
      parameters:
      - name: webhookId
        in: path
        description: The unique identifier of the webhook.
        required: true
        schema:
          type: string
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhookDTO'
    put:
      tags:
      - Webhooks
      summary: Update a webhook's details
      description: "Update the details of an existing webhook, such as its URL and active status. You must know the ID of the webhook to update it. To retrieve webhook IDs, see `GET /v1/op/webhooks`. To update a webhook's credentials, see `PUT /v1/op/webhooks/{webhookId}/credentials`.\n\n When updating a webhook, the webhook definition in your API call replaces the prior definition. You must provide the entire definition in the `PUT` call. If you omit values from the update request, those values are removed from the webhook. We recommend that you retrieve a webhook's details before you update the webhook with new values."
      operationId: Webhooks_UpdateWebhook
      parameters:
      - name: webhookId
        in: path
        description: The unique identifier of the webhook.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/designer.webhook.WebhookDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhookDTO'
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook
      description: Delete a specific webhook. You must know the ID of the webhook to delete it. To retrieve webhook IDs, see `GET /v1/op/webhooks`.
      operationId: Webhooks_DeleteWebhook
      parameters:
      - name: webhookId
        in: path
        description: The unique identifier of the webhook.
        required: true
        schema:
          type: string
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhookDTO'
  /v1/op/webhooks/{webhookId}/credentials:
    put:
      tags:
      - Webhooks
      summary: Update a webhook's credentials
      description: "Update the credentials to authenticate calls to the webhook endpoint. You must know the ID of the webhook to update it. To retrieve webhook IDs, see `GET /v1/op/webhooks`. To update a webhook's details, see `PUT /v1/op/webhooks/{webhookId}`.\n\n When updating a webhook, the webhook definition in your API call replaces the prior definition. You must provide the entire definition in the `PUT` call. If you omit values from the update request, those values are removed from the webhook. We recommend that you retrieve a webhook's details before you update the webhook with new values."
      operationId: Webhooks_UpdateWebhookCredentials
      parameters:
      - name: webhookId
        in: path
        description: The unique identifier of the webhook.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/designer.webhook.WebhookCredentialsDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhookDTO'
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook's credentials
      description: Delete the credentials for a webhook. You must know the ID of the webhook to delete its credentials. To retrieve webhook IDs, see `GET /v1/op/webhooks`.
      operationId: Webhooks_DeleteWebhookCredentials
      parameters:
      - name: webhookId
        in: path
        description: The unique identifier of the webhook.
        required: true
        schema:
          type: string
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhookDTO'
  /v1/op/webhooks/{webhookId}/testEvent:
    post:
      tags:
      - Webhooks
      summary: Test a webhook
      description: Send a test event to an existing webhook. This validates whether the webhook works. You must specify the webhook ID and an event type.
      operationId: Webhooks_SendTestEvent
      parameters:
      - name: webhookId
        in: path
        description: The unique identifier of the webhook.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/designer.webhook.WebhookEventTypeDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/designer.webhook.WebhookMessageResponseDTO'
components:
  schemas:
    designer.webhook.WebhookMessageResponseDTO:
      type: object
      properties:
        statusCode:
          type: integer
          description: The standard HTTP response code to inform you of the success or failure of the webhook notification attempt.
          format: int32
        message:
          type: string
          description: Information about the notification attempt.
        messageId:
          type: string
          description: The unique identifier of the message.
        eventId:
          type: string
          description: The unique identifier of the event that triggered the webhook notification.
      description: The results of the webhook notification attempt.
    designer.webhook.WebhookBasicAuthCredentialDTO:
      type: object
      properties:
        username:
          type: string
          description: The username for the webhook credential.
        password:
          type: string
          description: The password for the webhook credential.
      description: The basic authentication credentials for the webhook.
    designer.webhook.WebhookStatusDetailsDTO:
      type: object
      properties:
        isActive:
          type: boolean
          description: If `true`, the webhook is active.
        events:
          type: array
          items:
            $ref: '#/components/schemas/designer.webhook.WebhookEventTypeDTO'
          description: The events that the webhook is listening for.
      description: The webhook's details, such as its active status and the event types it's listening for.
    designer.webhook.WebhookStatusDTO:
      type: object
      properties:
        webhookId:
          type: string
          description: The unique identifier of the webhook.
        details:
          allOf:
          - $ref: '#/components/schemas/designer.webhook.WebhookStatusDetailsDTO'
          description: The webhook's details, such as its active status and the event types it's listening for.
      description: The webhook's status.
    designer.webhook.WebhookDetailsDTO:
      type: object
      properties:
        targetUrl:
          type: string
          description: The target URL to call when an event occurs.
        isActive:
          type: boolean
          description: If `true`, the webhook is active. Must be `false` when creating webhooks. Default is `false`.
        events:
          type: array
          items:
            $ref: '#/components/schemas/designer.webhook.WebhookEventTypeDTO'
          description: "The events that the webhook is listening for. Valid values:\n - `jobResultSuccess`: A job completed successfully.\n - `jobResultFailure`: A job failed to complete.\n - `jobReschedule`: A job was rescheduled.\n - `dvPublish`: A data version published to production.\n - `alertNotification`: A personalized alert notification was triggered.\n - `smartCompNotification`: A Smart Compensation event notification was triggered. This is available for Embedded Partners.\n - `dataUploadNotification`: A data file was uploaded.\n - `systemAlertNotification`: A system event alert notification was triggered.\n - `planRowPromotionNotification`: A row in a plan was promoted.\n - `auditEvent`: An audit event was triggered."
        keyName:
          type: string
          description: The display name of the encryption key for the webhook. Encryption key must use `HmacSHA256` algorithm.
        displayName:
          type: string
          description: The display name of the webhook.
      description: Information about the webhook, such as its URL, active status, and event types to listen for.
    designer.webhook.WebhookDTO:
      type: object
      properties:
        webhookId:
          type: string
          description: The unique identifier of the webhook.
        details:
          allOf:
          - $ref: '#/components/schemas/designer.webhook.WebhookDetailsDTO'
          description: The webhook's details, such as its URL, active status, and event types to listen for.
        credentialReference:
          type: string
          description: The unique identifier of the configured webhook credentials.
      description: The webhook's details, such as its URL, active status, and event types to listen for.
    Status:
      type: object
      properties:
        localizedMessage:
          type: string
          description: Localized error message describing the root cause of the error.
        code:
          type: string
          description: Error classification.
        message:
          type: string
          description: Not used.
        rci:
          type: string
          description: Optional root cause identifier.
        userError:
          type: boolean
          description: Indicates whether the error is a user error.
      description: The response structure for errors.
    designer.webhook.WebhookStatusesDTO:
      type: object
      properties:
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/designer.webhook.WebhookStatusDTO'
          description: The webhook statuses.
      description: The returned list of webhook statuses.
    designer.webhook.WebhookEventTypeDTO:
      type: object
      properties:
        eventType:
          type: string
          description: "The possible event types to listen for. Valid values:\n - `jobResultSuccess`: A job completed successfully.\n - `jobResultFailure`: A job failed to complete.\n - `jobReschedule`: A job was rescheduled.\n - `dvPublish`: A data version published to production.\n - `alertNotification`: A personalized alert notification was triggered.\n - `smartCompNotification`: A Smart Compensation event notification was triggered. This is available for Embedded Partners.\n - `dataUploadNotification`: A data file was uploaded.\n - `systemAlertNotification`: A system event alert notification was triggered.\n - `planRowPromotionNotification`: A row in a plan was promoted.\n - `auditEvent`: An audit event was triggered."
      description: The possible event types for Visier webhooks.
    designer.webhook.WebhooksDTO:
      type: object
      properties:
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/designer.webhook.WebhookDTO'
          description: A list of webhooks.
      description: The returned list of webhooks.
    designer.webhook.WebhookRequestDTO:
      type: object
      properties:
        details:
          allOf:
          - $ref: '#/components/schemas/designer.webhook.WebhookDetailsDTO'
          description: The webhook's details, such as its URL, active status, and event types to listen for.
        credentials:
          allOf:
          - $ref: '#/components/schemas/designer.webhook.WebhookCredentialsDTO'
          description: The webhook's credentials, such as a username and password or access token.
      description: The details and credentials for a webhook. Not required if your endpoint doesn't have authentication.
    designer.webhook.WebhookCredentialsDTO:
      type: object
      properties:
        basicAuth:
          allOf:
          - $ref: '#/components/schemas/designer.webhook.WebhookBasicAuthCredentialDTO'
          description: Authentication using a username and password.
        accessToken:
          type: string
          description: Authentication using an access token.
      description: The credentials to authenticate calls to the webhook endpoint. Must be one of `basicAuth` or `accessToken`. Not required if your endpoint doesn't have authentication.
  securitySchemes:
    CookieAuth:
      type: apiKey
      name: VisierASIDToken
      in: cookie
    ApiKeyAuth:
      type: apiKey
      name: apikey
      in: header
    BearerAuth:
      type: http
      scheme: bearer
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /v1/auth/oauth2/authorize
          tokenUrl: /v1/auth/oauth2/token
          scopes:
            read: Grants read access
            write: Grants write access
        password:
          tokenUrl: /v1/auth/oauth2/token
          scopes:
            read: Grants read access
            write: Grants write access
x-tagGroups:
- name: webhooks
  tags:
  - Webhooks