Webhooks APIs (Beta) for registering your own HTTPS endpoints with Visier and listening for platform events such as job success/failure, data version publish, alert notifications, data upload, plan row promotion, and audit events.
openapi: 3.0.3
info:
title: Visier Webhooks APIs
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
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.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.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.
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.
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.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.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.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.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.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.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.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.
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.
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
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.
security:
- ApiKeyAuth: []
BearerAuth: []
- ApiKeyAuth: []
CookieAuth: []
- ApiKeyAuth: []
OAuth2Auth: []
x-tagGroups:
- name: webhooks
tags:
- Webhooks