Using Webhooks to Notify External Services About Project Events in Virtuoso

Article Overview:

This article will cover how you can achieve the following:

Set up webhooks in Virtuoso to notify external services about specific project events automatically.

Problem Statement:

How can we automatically notify external services when certain events happen in a project?

Solution:

Virtuoso offers a webhook feature that sends a POST request to specified URLs when specific events occur in a project.

This article covers the following topics:

• Creating a Webhook: 
• Editing a Webhook
• Event Types
• Deliveries
• Payloads

Creating a Webhook:

1. Go to the desired project. 
2. Click on the Webhook Section.
   
   
   
3. Click on New Webhook
4. Fill out the following mandatory fields:

• Payload URL: URL to send POST requests (e.g., webhook. site).
• Content-Type: Choose application/JSON.
• Secret (optional):  User-generated random token for verifying requests.
• Description (optional):  Virtuoso webhook notification.
  

Note: For this exercise, we will use https://webhook.site/ to generate a random URL, customers should replace this step with the URL where they would like to receive the notifications. Copy the Unique URL and paste it Into a Notepad file.

5. Choose events to trigger the webhook:
   a. Send me everything (recommended).

   b. Let me select individual events.

6. Click on Create.

Example of Creating Webhooks:
1. Go to the Webhooks tab in the respective project.

2. Fill in the mandatory fields and optional fields if needed.

   

3. Click Create.
4. After Webhook Creation,  A ping event will automatically be triggered and notified at the payload URL.


5. When an execution event is triggered within the project, you will be notified at the payload URL.

Executing a journey:


Execution event: LAUNCHED

Execution event: STARTED

Execution event: FINISHED

Editing a webhook:

1. Navigate to the Webhook section of a project.
2. Click More and click the Edit option.
3. The edit screen is identical to the creation screen.
4. Update the webhook details as needed.
5. Click on Save.

Event types:

The following table lists the webhook event types available:

• Click the Down-arrow icon on a specific webhook in the management screen.
• View additional details, including a list of successful and unsuccessful deliveries of the webhook notifications.
  
  
  
  
• Each delivery has the following information:
  

1. Summary:
   

• • UUID: A unique identifier of the delivery.
  • Timestamp: The time when the request was made.
  • Duration: Time elapsed between sending the request and receiving the response.
    
    
    
    

2. Request information:
   

• • Request headers: Includes URL, method, content type, and other headers.
  • Payload: Sent in the POST request.

3. Response information (when Virtuoso receives a response from the payload delivery after contacting the provided URL)
   
   
   1. Response code: Status code received in the response;
   2. Response headers: All headers received back in the response;
   3. Response body: Body content received in the response.
      

Payloads:

Event payloads include the event type, organisation, project, and sender (if a

user triggered the event).

Execution event: 

Execution Event Example:

{

  "type": "EXECUTION",

  "event": "LAUNCHED|STARTED|UPDATED|FINISHED",

  "execution": { ... }, // the full execution details

  "goal": { ... },

  "sender": { ... },

  "project": { ... },

  "snapshot": { ... },

  "organization": { ... }

}

Ping event:

Ping Event Example:

{

  "type": "PING",

  "sender": {...},

  "organization": {...},

  "project": {...},

  "webhookId": XXXX,

  "webhook": {...}

}