# Webhooks

Webhooks allow external services to be notified when certain events happen at project level. When the specified events happen, we'll send a POST request to each of the URLs you provide.

The remaining of this section presents the following topics:

# Creating a webhook

To manage the webhooks associated with a project, click on the icon of a project and choose the Webhooks option. This will open the webhooks management screen:

No webhooks

Here you can add new webhooks by clicking on the icon in the upper right corner (or the Create webhook button if the project has no webhooks):

Create webhook

In this screen you should provide the following information:

  • Payload URL: Location to where the POST request should be sent;

  • Secret (optional): String token used to create a hash signature for each payload. The signature is sent along with each request in the X-Virtuoso-Signature header, and is a way of ensuring that the requests you receive came from Virtuoso. You should use a random string with high entropy in this field. In your server, you should use this secret and a HMAC hexdigest to compute the hash signature of the received payload and compare the result with the signature received in the request header. The hash signature starts with sha1=. To avoid certain timing attacks, you should use a method that performs a "constant time" string comparison;

  • Content-type: Choose one of the available options to control how the webhook payload is delivered: application/json delivers the JSON payload directly as the body of the POST request, and application/x-www-form-urlencoded delivers the JSON payload as a form parameter called payload;

  • Description (optional): Text that help you identify the webhook;

  • List of events: Events that should trigger the webhook. You can specify that all current and future events should trigger your webhook by choosing Send me everything in the user interface. If you choose Let me select individual events, only the events selected will trigger the webhook.

Let me select individual events

New event types added to Virtuoso after creating the webhook will be deselected by default when the Let me select individual events option is used.

# Editing a webhook

From the webhooks management screen, you can edit a webhook by clicking on the icon in the upper right corner associated with it and choosing the "Edit" option. The edit screen is identical to the creation screen presented.

# Event types

The following table lists the webhook event types available:

Name Description
Execution Execution event (such as LAUNCHED, STARTED, UPDATED, and FINISHED).
Ping An event triggered automatically after the webhook creation to check if it was configured correctly. It can be re-triggered by choosing the Ping option in the project context menu

# Deliveries

You can access additional information by clicking on the arrow down icon of a specific webhook in the management screen. This will include a list of successful or unsuccessful delivery attempts:

Webhook deliveries

Each delivery has the following information:

  1. Summary

    • UUID: A unique identifier of the delivery;

    • Timestamp: Time when the request was made;

    • Duration (when present): Time elapsed between sending the request and receiving the response.

  2. Request information

    • Request headers: This includes request URL, method, content type of the request, and all other headers we send on our request;

    • Payload: Payload sent in the POST request.

  3. Response information (when Virtuoso receives a response from the payload delivery after contacting the provided URL)

    • Response code: Status code received in the response;

    • Response headers: All headers received back in the response;

    • Response body: Body content received in the response.

The duration, request, and response information are only shown when a delivery item is expanded.

Webhook delivery request

Webhook delivery response

The payload of each delivery item can be re-delivered as needed, by clicking on the Re-deliver icon .

# Payloads

All event payloads will include the type of the payload. All non-ping event payloads, will include the organization and the project on which the event occurred. The sender will also be included when the event was performed by a user.

Key Type Description
type string PING or EXECUTION
sender object Id, name, and email of the user who performed the event
organization object Id and name of the organization
project object Id and name of the project

Each event type has a specific payload format so that the payload can provide information about the event, which are described in the following sections.

# Execution event

Key Type Description
execution object Information about the execution
goal object Information about the related goal
snapshot object Information about the related snapshot

# Example:

  "type": "EXECUTION",
  "execution": { ... }, // the full execution details
  "goal": { ... },
  "sender": { ... },
  "project": { ... },
  "snapshot": { ... },
  "organization": { ... }

# Ping event

Key Type Description
hook_id integer The ID of the webhook that triggered the ping
hook object The webhook configuration

# Example:

  "type": "PING",
  "sender": {
    "id": 1,
    "name": "admin",
    "email": "[email protected]"
  "project": {
    "id": 1,
    "name": "Test Project"
  "webhook": {
    "id": 1,
    "active": true,
    "secret": "********",
    "archived": false,
    "projectId": 1,
    "payloadUrl": "http://localhost:8000/api/webhooks/payload",
    "contentType": "application/json",
    "description": "",
    "sslVerification": false
  "webhookId": 1,
  "organization": {
    "id": 1,
    "name": "SpotQA"
Last Updated: 9/29/2023, 12:34:53 PM