Webhooks: Real-Time Event Delivery to HTTP Endpoints

Webhooks let you push VISO TRUST events to an external HTTP endpoint in real time. Use them to build custom integrations with systems that don’t have a native VISO TRUST connector: GRC platforms, ticketing systems, SIEMs, data warehouses, or internal tooling. You manage webhooks through the VISO TRUST REST API under /api/v1/webhooks. See Authentication for how to generate an API token.

How webhooks work

When a subscribed event occurs in VISO TRUST (for example, an assessment completes), VISO TRUST sends an HTTP POST request to the URL you registered. The request body is a JSON payload describing the event. Your endpoint receives the payload and can use it to trigger downstream actions, such as creating records, sending alerts, or syncing data.

Managing webhooks

You create and manage webhooks through the API. Every endpoint requires a token from an Admin or Program Manager account.

Method & path	Purpose
`POST /api/v1/webhooks`	Register a webhook. Provide the endpoint URL and the trigger types to subscribe to
`GET /api/v1/webhooks`	List your organization’s registered webhooks
`GET /api/v1/webhooks/{webhookId}`	Retrieve a single webhook
`PUT /api/v1/webhooks`	Update a webhook’s URL or subscribed trigger types
`DELETE /api/v1/webhooks/{webhookId}`	Remove a webhook

Your endpoint should accept HTTP POST requests, return a 2xx response to acknowledge receipt, and be publicly reachable from VISO TRUST’s servers.

Registering a webhook

POST /api/v1/webhooks takes a JSON body with these fields:

Field	Required	Description
`serviceType`	Yes	The delivery format. Use `GENERIC` for a plain HTTP endpoint. `SLACK`, `DISCORD`, and `TEAMS` send a message formatted for that product’s incoming-webhook URL; `WORKATO` is used by the Workato-powered automations.
`webhookUrl`	Yes	The endpoint VISO TRUST posts to.
`eventTypes`	Yes	One or more trigger types from Event Types. Must not be empty.
`description`	No	A label for your own reference, returned on reads.
`id`	On `PUT` only	The webhook’s ID. Omit it on `POST`; `PUT` rejects a body without it.

curl -X POST "https://app.visotrust.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceType": "GENERIC",
    "webhookUrl": "https://example.com/hook",
    "description": "Prod GRC intake",
    "eventTypes": ["ASSESSMENT_COMPLETED", "RELATIONSHIP_ONBOARDED"]
  }'

PUT /api/v1/webhooks replaces the whole configuration, so send every field you want to keep (including eventTypes) alongside the id. Deleting a webhook is safe to retry. DELETE /api/v1/webhooks/{webhookId} returns 200 when the webhook is removed and 404 when the ID is unknown or the webhook was already deleted. For example:

curl -X DELETE "https://app.visotrust.com/api/v1/webhooks/12345" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Event types

Subscribe a webhook to one or more of the following trigger types. Events are grouped into assessment and relationship categories.

Assessment events

Trigger	When it fires
`ASSESSMENT_COMPLETED`	An assessment reaches Completed status
`ASSESSMENT_RECERTIFICATION_COMPLETED`	A recertification assessment completes
`ASSESSMENT_REMEDIATION_COMPLETED`	A remediation assessment completes
`ASSESSMENT_ARTIFACT_UPDATE_COMPLETED`	An artifact-update assessment completes
`DOCS_ONLY_ARTIFACT_UPDATE_COMPLETED`	A documents-only artifact update completes
`ASSESSMENT_GENERATED_SUMMARY_CREATED`	An AI assessment summary is generated
`ASSESSMENT_REMINDER`	A reminder is sent for an assessment
`ASSESSMENT_CANCELLED`	An assessment is cancelled (by vendor, client, or admin)
`ASSESSMENT_CANCELLED_BY_AUDITOR`	An assessment is cancelled by an auditor
`ASSESSMENT_AUTOMATICALLY_CANCELLED`	An assessment is automatically cancelled
`ASSESSMENT_EMAIL_BOUNCED`	An assessment email to a vendor contact bounces

Relationship events

Trigger	When it fires
`RELATIONSHIP_ONBOARDED`	A relationship is onboarded
`RISK_ACCEPTED`	Risk is accepted on a relationship
`RELATIONSHIP_OVERDUE`	A relationship becomes overdue
`UPCOMING_RECERTIFICATION`	A relationship is approaching recertification
`ARTIFACT_EXPIRED`	An artifact on the relationship has expired

For advance warning before an artifact expires, use lifecycle management rather than a webhook. VISO TRUST surfaces expiring artifacts as an in-app notification. On relationships with lifecycle management enabled, it also requests updated documentation ahead of the expiration date. See Lifecycle Management.

Payload structure

Every webhook delivery uses the same flat JSON payload. The message field carries the event name; relationshipId and assessmentId reference the affected records (assessmentId may be omitted for relationship-only events).

{
  "relationshipId": 12345,
  "assessmentId": 67890,
  "message": "ASSESSMENT_COMPLETED"
}

Use the IDs to fetch full details from the API (for example, GET /api/v1/relationships/{relationshipId}).

Trigger types vs. delivered event names

For most triggers the message value matches the trigger type you subscribed to. Two do not. Subscribe by the trigger type, but match on the delivered value:

Trigger type (what you subscribe to)	`message` value (what you receive)
`ASSESSMENT_REMEDIATION_COMPLETED`	`REMEDIATION_ASSESSMENT_COMPLETED`
`ASSESSMENT_EMAIL_BOUNCED`	`EMAIL_BOUNCED`

For the same reason, the eventTypes array returned by GET /api/v1/webhooks lists the underlying event names rather than the trigger types you posted. A webhook subscribed to ASSESSMENT_CANCELLED reads back as four entries: ASSESSMENT_CANCELLED, ASSESSMENT_CANCELLED_BY_VENDOR, ASSESSMENT_CANCELLED_BY_CLIENT, and ASSESSMENT_CANCELLED_BY_ADMIN. That one trigger covers every cancellation path except auditor and automatic cancellation, which have their own triggers. Deliveries for all four still arrive with message set to ASSESSMENT_CANCELLED.

Delivery behavior

VISO TRUST sends deliveries asynchronously as an HTTP POST with Content-Type: application/json. Your endpoint should respond quickly with a 2xx status.

Webhook payloads are not currently signed. Because there is no signature header to verify, protect your endpoint another way. Use a long, unguessable URL, restrict inbound traffic to VISO TRUST, and treat the payload IDs as references to be confirmed against the API rather than as trusted data.

Failure handling

VISO TRUST tracks consecutive delivery failures per webhook. A failure is any non-2xx HTTP response or a connection error. A successful delivery, or saving the webhook (PUT /api/v1/webhooks), resets the failure count to zero and clears any warning state. Behavior at the third consecutive failure depends on the webhook type:

Type	Behavior after 3 consecutive failures
`WORKATO`	VISO TRUST automatically unsubscribes and removes the webhook. To resume delivery, register the webhook again.
`GENERIC`, `SLACK`, `DISCORD`, `TEAMS`	The webhook remains subscribed and continues to receive future events. VISO TRUST sends a one-time warning email to `support@visotrust.com` and does not send another for the same webhook, even after recovery.

VISO TRUST does not replay missed events. Once a failing webhook recovers, it only receives events that fire after recovery.

Monitoring delivery health

GET /api/v1/webhooks and GET /api/v1/webhooks/{webhookId} return two fields you can poll to detect failing deliveries:

Field	Description
`consecutiveFailureCount`	Number of consecutive failed delivery attempts. `0` when the most recent delivery succeeded.
`firstFailureAt`	Timestamp (ISO 8601) of the first failure in the current run, or `null` when the last delivery succeeded.

Example response:

{
  "id": 12345,
  "serviceType": "GENERIC",
  "webhookUrl": "https://example.com/hook",
  "description": "Prod GRC intake",
  "eventTypes": ["ASSESSMENT_COMPLETED", "RELATIONSHIP_ONBOARDED"],
  "consecutiveFailureCount": 2,
  "firstFailureAt": "2026-09-17T14:22:10Z"
}

During development, tools like Webhook.site or ngrok let you receive and inspect webhook payloads without running a production server.

Example: edit the AI summary when it’s generated

Subscribe to ASSESSMENT_GENERATED_SUMMARY_CREATED to rewrite the AI assessment summary automatically. For example, you can pass it through your own template or language model. The summary endpoints require a token from an Admin account.

Read the summary

When the webhook fires, fetch the summary with the assessmentId from the payload. Pass format=markdown to get plain Markdown instead of HTML.

curl "https://app.visotrust.com/api/v1/assessments/67890/summary?format=markdown" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "id": 67890,
  "summary": "## Summary\n\nAcme Corp maintains a SOC 2 Type II report...",
  "version": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "edited": false
}

version identifies this revision of the summary. edited is true when someone has changed the generated summary.

Write the edited summary

Send the edited text to PUT /api/v1/assessments/{id}/summary. Include the version you read so VISO TRUST rejects the edit if the summary changed in the meantime.

curl -X PUT "https://app.visotrust.com/api/v1/assessments/67890/summary" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "## Summary\n\nAcme Corp is approved for production data...",
    "format": "markdown",
    "version": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  }'

The response returns the updated summary in the format you sent, with a new version.

Field	Required	Description
`summary`	Yes	The edited summary, up to 1,000,000 characters.
`format`	No	`markdown` or `html`. Defaults to `html`. VISO TRUST renders Markdown with the report’s own styling.
`version`	No	The `version` from your last read. If the summary no longer matches it, VISO TRUST returns `409 Conflict` with the error key `STALE_VERSION`. Read the summary again and reapply your edit.

The edit works the same as editing the summary in the app. VISO TRUST keeps the generated summary, shows your edit in its place, and records it in the summary’s edit history. Regenerating the summary discards the edit. This happens automatically when a new assessment completes. VISO TRUST returns 400 Bad Request in these cases:

The assessment is not completed.
The assessment has no AI-generated summary.
The summary is empty after VISO TRUST removes unsupported markup.

VISO TRUST sanitizes every edit before storing it. It removes scripts, event handlers, external stylesheets, and remote images. Embed images as data: URIs.

Getting Started

Third Parties

Risk & Monitoring

Trust & Questionnaires

VISO Chat Agent

Integrations

Organization Settings

Webhooks: Real-Time Event Delivery to HTTP Endpoints

How webhooks work

Managing webhooks

Registering a webhook

Event types

Assessment events

Relationship events

Payload structure

Trigger types vs. delivered event names

Delivery behavior

Failure handling

Monitoring delivery health

Example: edit the AI summary when it’s generated

​How webhooks work

​Managing webhooks

​Registering a webhook

​Event types

​Assessment events

​Relationship events

​Payload structure

​Trigger types vs. delivered event names

​Delivery behavior

​Failure handling

​Monitoring delivery health

​Example: edit the AI summary when it’s generated

How webhooks work

Managing webhooks

Registering a webhook

Event types

Assessment events

Relationship events

Payload structure

Trigger types vs. delivered event names

Delivery behavior

Failure handling

Monitoring delivery health

Example: edit the AI summary when it’s generated