Webhooks

Webhooks let your server react to events on the Vlens platform in real time, without polling. When an event occurs, Vlens sends an HTTP POST with a JSON payload to a URL you configure in the Vlens portal.

Use cases

Webhooks support:

• Tracking contract lifecycle changes (creation, approval, signing, countersignature)
• Synchronizing contract status with external systems
• Triggering automated workflows on contract events
• Maintaining audit and monitoring dashboards

Available events

Setting up a subscription

1. Sign in to the Vlens portal
2. Navigate to Webhook Subscriptions
3. Click Add New Webhook Subscription
4. Provide:
   • Webhook Endpoint — the URL that will receive POST notifications
   • Webhook Events — one or more events to subscribe to
5. Click Save

Subscriptions are event-specific and endpoint-specific — multiple subscriptions can target the same event with different endpoints (useful for fan-out to different downstream systems).

Payload format

Every webhook delivery is a POST with a JSON body:

1
{
2
  "Id": "2b020a26-ec12-4f59-8e6a-7d4bf941372b",
3
  "WebhookEvent": "App.BusinessRequestStatusChange",
4
  "Attempt": 1,
5
  "Data": {
6
    "Id": "c2f27bd2-bb49-4dde-bb5f-22a6b8e0d20d",
7
    "NewStatus": "PendingApproval"
8
  },
9
  "CreationTimeUtc": "2025-12-11T11:27:18.6197007Z"
10
}

Data for BusinessRequestStatusChange

Receiving a webhook

1
import express from "express";
2
3
const app = express();
4
app.use(express.json());
5
6
app.post("/webhooks/vlens", (req, res) => {
7
  const { Id, WebhookEvent, Data, Attempt } = req.body;
8
9
  // Acknowledge receipt quickly — process async
10
  res.status(200).send("ok");
11
12
  // Deduplicate using Id
13
  if (alreadyProcessed(Id)) return;
14
  markProcessed(Id);
15
16
  if (WebhookEvent === "App.BusinessRequestStatusChange") {
17
    handleContractStatusChange(Data.Id, Data.NewStatus);
18
  }
19
});
20
21
app.listen(3000);

Delivery logs

Every webhook delivery is logged and viewable in the Vlens portal. Each log entry includes:

• HTTP method (POST)
• Source IP address
• Timestamp
• Request headers
• Request body

Use the delivery log to debug failed or unexpected deliveries.

Common patterns

Reconcile on completion

1
if (WebhookEvent === "App.BusinessRequestStatusChange"
2
    && Data.NewStatus === "ServiceProviderSigned") {
3
  // Contract fully executed — sync to internal systems and notify the customer
4
  await crm.markContractCompleted(Data.Id);
5
  await sendCustomerNotification(Data.Id);
6
}

Polling fallback

For mission-critical workflows, combine webhooks with periodic polling of GET /api/BusinessRequest/CurrentListIds to catch any missed deliveries.