> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visotrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks: real-time event delivery to HTTP endpoints

> Push VISO TRUST events to any HTTP endpoint in real time — assessment completions, recertifications, and relationship lifecycle events for your systems.

**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.

Webhooks are managed through the VISO TRUST REST API under `/api/v1/webhooks`. See [Authentication](/api-reference/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 — creating records, sending alerts, or syncing data.

## Managing Webhooks

Webhooks are created and managed via the API:

| 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.

## 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                   |
| `REMEDIATION_ASSESSMENT_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                 |

### 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_EXPIRING`        | An artifact on the relationship is approaching expiration |
| `ARTIFACT_EXPIRED`         | An artifact on the relationship has expired               |

## 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).

```json theme={null}
{
  "relationshipId": 12345,
  "assessmentId": 67890,
  "message": "ASSESSMENT_COMPLETED"
}
```

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

## Delivery Behavior

Deliveries are sent asynchronously as an HTTP POST with `Content-Type: application/json`. Your endpoint should respond quickly with a `2xx` status.

<Note>
  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.
</Note>

<Tip>
  During development, tools like [Webhook.site](https://webhook.site) or [ngrok](https://ngrok.com) let you receive and inspect webhook payloads without running a production server.
</Tip>