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
• Editing a webhook
• Event types
• Deliveries
• Payloads

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:

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):

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:

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.

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
event	string	LAUNCHED, STARTED, UPDATED, or FINISHED
execution	object	Information about the execution
goal	object	Information about the related goal
snapshot	object	Information about the related snapshot

Example:

{
  "type": "EXECUTION",
  "event": "LAUNCHED|STARTED|UPDATED|FINISHED",
  "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"
  }
}