Webhooks can be used to automatically publish your website once you've finished building your Vev project. Essentially, a webhook is an HTTP POST request that contains the data needed to publish your Vev project. This request is sent to a webhook receiver, which can be another application or service responsible for handling the publishing process. The webhook receiver processes the data, which can include HTML, CSS, and JavaScript files, and publishes the website to your desired location, such as a web server or content delivery network (CDN).

Once the webhook is set up, the publishing process is fully automated, reducing the time and effort required to publish the website manually.

Our webhook integration is straightforward, and the receiving service must respond with a 2xx HTTP status code to indicate success. Any other response code will be considered an error, and requests have a 20-second timeout.

Creating a Webhook Trigger

To create a webhook trigger:

In the dashboard, click your avatar in the left sidebar and select Hosting.
Click Create hosting.
Enter your domain or sub-domain (e.g., www.mywebsite.com) for navigation purposes. You will add your Webhook URL in the next stage.
Select Advanced Hosting as the hosting option.
Choose Webhook Trigger from the list.
Set the access level (public or private).
Click Create hosting.

☝️ Upgrade to the Professional plan to unlock Webhook integrations as an Advanced hosting option!

Setting up a Webhook trigger

To successfully connect your Webhook trigger, you'll need to configure several parameters. Some are mandatory, while others are optional based on your server configuration.

Take a look at the list below to understand each parameter's function:

Webhook URL (required): This is the address (e.g., https://www.yourwebhookurl.here) where Vev will send the content when you publish from the platform. If you don’t have a server or endpoint available, you can use a tunneling service like Ngrok to direct content to your local machine.
Page content to send in addition to the body:
- Send full page: Enable this option to have Vev generate the complete page, including the HTML structure (<html /> and all). If disabled, only the HTML required to render the content will be sent.
- Send plugin settings: Attach generated data from your integrations (e.g., Google Analytics, Google Tag Manager) as a JSON attribute in the payload.
Payload Settings:
If you encounter publishing issues, select Content as links to send a list of HTML files instead of embedding the code directly in the payload’s pages field.
How to handle assets:
Select Include asset URLs in payload to include URLs for assets (images, fonts, videos, etc.) in your webhook payload. Learn more here.
Ping:
Enable this option to allow Vev to send pings.
Unpublish:
Enable this option to allow Vev to unpublish content.

👀 Explore our Webhook receiver example implementation on our public GitHub repository.

Gain a comprehensive understanding of all Webhook event types, documented for your reference.

Webhook with Self-Hosted Assets

For projects requiring full offline access or complete control over asset files, there’s an option to serve all published project files and assets from the same location. This ensures that all references to assets are replaced, pointing to an "assets" folder on the same web server as the HTML. When the webhook is triggered, the receiver will receive a list of all HTML files and asset URLs used in the project.

How to Enable

To enable this feature, follow these steps:

Go to Hosting Settings for any webhook hosting.
Enable the option Include asset URLs in payload.
Optionally, provide a custom folder name for the assets folder (defaults to "assets").

How to Use

Once the webhook is triggered with a PUBLISH event, your server application will need to:

Download all HTML files and assets within 24 hours, as Vev deletes the files after this period.
Process and store the files and assets on your web server.

You can find a simple example of a receiver and web server implementation here.

Required Steps

Download all HTML files and store them in a folder called {payload.dir}.
Note: Vev project page links do not use .html extensions. Some web servers handle this without issue, while others may need additional configuration.
Download all assets and store them in {payload.dir}/{payload.assetsFolder}.

Signature

The token, set by you, can be anything and is crucial for verifying that the content originates from Vev. To view or generate a Secret for your webhook, click on "Generate token." This string of characters is utilized in the Webhook server code.

When publishing via a Webhook, all requests from Vev are signed with a header called X-Vev-Signature, allowing you to verify the content's origin. To verify the signature, you'll need the secret you set in Vev and a crypto library to create HMAC digests.

The X-Vev-Signature consists of the algorithm used to generate the hash and the signature itself, for example, sha512=super-long-hashed-value. We only support the sha512 algorithm for generating signatures at this time.

Endpoint security

We support the following authentication methods for communication with your endpoints:

Non-secured endpoints
Basic authentication
Token-based authentication

OpenID Connect (OIDC) is not supported yet.

Additional security

All webhook requests will originate from the IP address 34.72.55.20, which is owned by Vev. However, relying solely on IP validation is not sufficient for security. To enhance protection, you should also implement additional measures such as validating signatures or verifying security headers.

Additional Domain Settings

Adding a Web Path

You can add a base path to your domain, which will be used for all projects published under that domain.

Select Your Default Content Language

Set the default content language for your projects, ensuring proper display and functionality of your text content across different locales.

Adding a Favicon

A favicon is a small visual representation of your webpage that helps users identify your site among multiple open tabs. Simply drag and drop the favicon file into the designated area.

Publishing via Webhook

To publish via a Webhook:

Open the project you want to publish.
Click the Publish button in the top-right corner.
Select Add Publish Destination from the publish dialog.
Choose your domain from the dropdown list.
Optionally, add a path to your domain, or leave it blank to publish to the root.
Hit Add Publish Destination.
Open the publish dialog again and click Publish Project.

To publish via your Webhook, you need to upgrade to our Professional plan.

Unpublishing a Project

You have two options for unpublishing a project via Webhook:

From the Publishing Modal:
- Click on the Publish button to access the Publishing Modal.
- Find your domain, then click the overflow menu (three dots).
- Select Unpublish, confirm your choice, and wait for up to 5 minutes for the change to take effect.
From the Webhook Settings Page:
- Go to the Projects tab in your Webhook settings.
- Find the project you want to unpublish, click the three dots, and select Unpublish.