Setup webhooks

Webhooks enable you to listen for events happening in the Verta platform and automatically trigger certain actions. You can use webhooks to automate and integrate your ML pipeline, CI/CD workflows, security scans and more. For example, you can trigger a deployment pipeline if a model version is approved to transition to the production stage.

The alpha version of Verta webhook setup will allow customer admins to setup and test your webhook integration. You will require system admin credentials in order to create any webhooks.

Test the webhook setup

1. Setup the payload URL where Verta will post information (e.g. https://smee.io/)

2. Create a test webhook: You can create a webhook in Verta using the REST API.In the API provide the following information:

   • name: Unique webhook name (names must be unique within a workspace)

   • location: Payload URL where verta system will trigger and send the event info

   • mutual_secret (optional): A shared secret between the two sides for validation

   • event_types: This could be event types like: CREATE, UPDATE, READ, DELETE

   • all_events: If true, we don't filter events that trigger the webhook by the event_type field. If false, we filter events using only the values in the event_types field

Request

curl -X POST \
 https://yourenvironment.dev.verta.ai/api/v1/uac-proxy/events/createWebhook \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'grpc-metadata-developer_key: XXXXX' \
  -H 'grpc-metadata-email: [e-mail]' \
  -H 'grpc-metadata-source: PythonClient' \
  -H 'postman-token: XXXXX' \
  -d '{
    "name": "webhook_unique_name",
    "location": "https://verta.ai/webhook/location",
    "event_types": ["CREATE","READ"],
    "all_events": false
   }'

Response

{
    "id": 1
    "name": "webhook_unique_name",
    "location": "https://verta.ai/webhook/xyz",
    "mutual_secret": "",
    "event_types": ["CREATE","READ"],
    "all_events": false
}

The response returns a unique id for the webhook.

3. Trigger a test webhook: Once a webhook is created, you can trigger and send a test event to the payload URL and verify the message. The payload endpoint receives status code and a message body.

Request

curl -X POST \
  https://yourenvironment.verta.ai/api/v1/uac-proxy/events/triggerTest \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'grpc-metadata-developer_key: XXXXX' \
  -H 'grpc-metadata-email: [e-mail]' \
  -H 'grpc-metadata-source: PythonClient' \
  -H 'postman-token: XXXXX' \
  -d '{
	"webhook_id": 1
}'

Response

{
    "status_code": 200
}

Verify the message in the payload URL. Here is an example of the event.

Available Events

Registered Model Version Promotion Event

The RMV Production Promotion Event webhook allows you to create an automation when someone promotes a Registered Model Version to Production stage. An event will fire to your configured webhook endpoint after a promotion to “Production” via the UI after the stage change is approved.

You may use this to set up model governance or process automation based on the status of models in the development lifecycle. For example, you can copy model builds and metadata into another deployment system using a Jenkins pipeline that runs when the webhook is sent. For this case, we provide a “promotion in Progress” UI alert and you should use the API to send a forwarding address (URL) to platform where users can learn more about where the model was deployed.

This webhook event is behind a feature flag, please let us know if you need it enabled. Please set up and configure webhooks before proceeding. Then you will need to create the webhook following the instructions below.

To create the event webhook and subscribe to it, please send the following curl command with your own user info and key.

curl --location --request POST 'https://yourenvironment.verta.ai/api/v1/uac-proxy/events/createWebhook' \
--header 'grpc-metadata-developer_key:XXXXX' \
--header 'grpc-Metadata-email: [e-mail]' \
--header 'grpc-metadata-source: PythonClient' \
--header 'Content-Type: application/json' \
--data-raw '{
	"name": "promotion webhook 1",
	"workspace_id": 1,
	"location": "https://verta.ai/webhook/location",
	"event_types": ["PROMOTE"],
	"resource_types": [
    	{ "modeldb_service_resource_type": "REGISTERED_MODEL_VERSION" }
	],
	"all_events": false
}'

Once you’ve set this up, when the event occurs the webhook will send you relevant information about the Registered Model Version which was promoted. Here is the sample payload you can expect to receive at your configured endpoint:

{
    	"id": "691",
    	"registered_model_id": "716",
    	"version": "ModelVersion 116576560158156881",
    	"time_updated": "1657656459104",
    	"time_created": "1657656015885",
    	"readme_text": "readme text goes here",
    	"owner": "1041",
    	"attributes": [
        	{
            	"key": "__verta_reserved__model_language",
            	"value": "Python"
        	},
        	{
            	"key": "__verta_reserved__model_type",
            	"value": "StandardVertaModel"
        	}
    	],
    	"stage": "UNASSIGNED",
    	"lock_level": "OPEN",
    	"version_number": "6"
	}

In the platform UI, users will see a promotion in progress alert to let them know that the model is being sent to the production cluster.

Once your process is complete, use the Verta platform API to update the promotion status to “complete” and provide a forwarding address.

Make call to Registry with a payload similar to this example: Take special note of the redirect_metadata information.

{
    	"id": "691",
    	"registered_model_id": "716",
    	"version": "ModelVersion 116576560158156881",
    	"time_updated": "1657656459104",
    	"time_created": "1657656015885",
   	 
    	"readme_text": "readme text goes here",
    	"owner": "1041",
    	"attributes": [
        	{
            	"key": "__verta_reserved__model_language",
            	"value": "Python"
        	},
        	{
            	"key": "__verta_reserved__model_type",
            	"value": "StandardVertaModel"
        	}
    	],
    	"stage": "UNASSIGNED",
    	"lock_level": "OPEN",
    	"version_number": "6",
    	"redirect_metadata": "https://newurl.com/2"
	}

Custom External Security Scanning Event

The Security Scanning Webhook allows you to receive an event when a user requests that a model be scanned for vulnerabilities. This webhook event is available behind a feature flag, please let us know if you'd like it enabled.

The high level process enabled by this webhook is:

1. You will recieve an event when a model needs to be scanned. Data scientists and other users can request scanning from the registered model version page

2. A scannable build will be created (if one does not already exist) for the model and you will receive the model name and build id to scan via the webhook

3. You may scan the build using one or more of your preffered vendors

4. You can return the results of the scan into the Verta platform and UI - specifcially, you may indicate if the model passed or failed the scan based on your business rules. You may also provide a url to view more details

To create this webhook, send the following curl command with your own credentials:

curl --location --request POST 'https://yourenvironment.verta.ai/api/v1/uac-proxy/events/createWebhook' \
--header 'grpc-metadata-developer_key:XXXXX' \
--header 'grpc-Metadata-email: [e-mail]' \
--header 'grpc-metadata-source: PythonClient' \
--header 'Content-Type: application/json' \
--data-raw '{
	"name": "external scanning webhook 1",
	"location": "your_webhook_url_goes_here",
	"event_types": ["REQUEST_SCAN"],
	"resource_types": [
    	{ "deployment_service_resource_type": "BUILD" }
	],
	"all_events": false
}'

Once this is set up, you will begin gettting events for builds to scan. Note: It may take a few minutes between a user requesting a scan and the webhook being sent, as the build is being created. If there are errors in the build, the user will be notified.

The webhook you recieve will contain:

{
	"id": "(hash)"
	"timestamp": "{timestamp of webhook}"
	"event_type": "REQUEST_SCAN"
	"resource_type": "BUILD"
	"workspaceID": 0
	"updated" : {
		"buildID": "{id of build to scan}
		"imageurl" : "url of image to scan"
	}
}

Once your scan is complete, you can return information about the scan to Verta via API.

Here is an example of a curl command that can be copy-pasted. Make sure to update the workspace name and buildID in the url and the user email and dev key in the headers:

 curl -X PUT "https://<HOST>.verta.ai/api/v1/deployment/workspace/<WORKSPACE_NAME>/builds/<BUILD_ID>/scan" \                                          
                 -H "accept: application/json" \
                 -H "Content-Type: application/json" \
                 -d "{ \"scan_external_results\": { \"safety_status\": \"safe\", \"url\": \"https://www.urltoscanresults.com\" }, \"scan_status\": \"scanned\"}" \
                 -H 'grpc-metadata-developer_key:<DEV_KEY>' \
                 -H 'grpc-Metadata-email: <EMAIL>' \
                 -H 'grpc-metadata-source: PythonClient'

We accept "safe" or "unsafe" as a result of the scan, and this will be used to determine promotion and deployment elegibility of a model.

Once this API call is received the verta platform will show the user the result of the scan.