Alternative integration

Webhooks

Configure, receive, and authenticate real-time consumer leads from Vikk AI Ad Center via signed HTTP POST requests.

Overview

Vikk AI Ad Center outbound webhooks allow law firms using custom intake platforms or unsupported CRMs to receive live-generated lead data instantaneously. Webhooks are delivered via secure HTTP POST requests containing versioned, canonical case metadata payload bodies signed with cryptographic hashes.

Webhook setup

Expose a public endpoint. Set up a publicly accessible HTTPS endpoint on your server (e.g. https://api.yourfirm.com/vikk-leads). Non-HTTPS endpoints will be rejected.
Create a webhook connection. In Vikk AI Lawyer Ad Center, navigate to Webhook Configurations and click Create Webhook. Provide your endpoint URL and a friendly name.
Secure your signing secret. Once created, copy the generated signing_secret from the response or configuration modal. Store this secret securely in your server's environment variables. It is encrypted on our servers and cannot be retrieved later.
Toggle enabled state. Set the webhook to enabled. All future qualified leads will now automatically dispatch to your URL.

Security requirement

Webhooks are delivered using live consumer contact details. You MUST verify the cryptographic signature on every incoming request to guarantee authenticity and prevent unauthorized access or replay attacks.

Incoming dispatch format

Request headers

Header	Description
`Content-Type`	Always application/json.
`X-Vikk-Signature`	Cryptographic signature of the raw JSON body, prefixed with `sha256=` (e.g. `sha256=a88b56f...`).
`X-Vikk-Timestamp`	The Unix epoch timestamp (seconds) when the payload was dispatched.
`X-Vikk-Idempotency-Key`	Unique key to identify duplicates. Structured as: `webhook-leadId-timestamp`.

JSON body payload

json

{
  "event_id": "evt_ab12cd34ef56",
  "event_type": "lead.created",
  "schema_version": "v1.0.0",
  "timestamp": "2026-07-30T13:30:00Z",
  "lead_id": "60c72b2f9b1d8a001c8b4567",
  "business_id": "60c72b2f9b1d8a001c8b4111",
  "contact": {
    "name": "Jane Doe",
    "email": "janedoe@example.com",
    "phone": "555-555-1234",
    "zipcode": "90210"
  },
  "legal_specialty": "Family Law",
  "summary": "Detailed lead conversation summary...",
  "v_score": {
    "score": 88,
    "tier": "A",
    "rationale": "High intent and matching match tier."
  },
  "consent": true
}

Verifying signatures

Use the following sample code in your Express.js backend to parse, verify signatures, and handle Vikk AI Ad Center webhooks securely:

javascript

const crypto = require("crypto");
const express = require("express");
const app = express();

// 1. Capture raw request body to compute hash accurately
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString();
  }
}));

app.post("/vikk-leads", (req, res) => {
  const secret = "YOUR_FIRM_SIGNING_SECRET"; // Copy this from your Vikk dashboard
  const signatureHeader = req.headers["x-vikk-signature"];
  const timestampHeader = req.headers["x-vikk-timestamp"];

  // 2. Validate timestamp age (protect against replay attacks)
  const currentTimestamp = Math.floor(Date.now() / 1000);
  if (!timestampHeader || Math.abs(currentTimestamp - Number(timestampHeader)) > 300) {
    return res.status(400).send("Request expired or timestamp invalid");
  }

  // 3. Compute cryptographic signature
  const expectedSignature = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("hex");

  // 4. Compare signatures
  if (signatureHeader !== expectedSignature) {
    return res.status(401).send("Invalid request signature");
  }

  // 5. Check idempotency key to avoid duplicate intake processes
  const idempotencyKey = req.headers["x-vikk-idempotency-key"];
  console.log(`Lead received. ID: ${req.body.lead_id}, Key: ${idempotencyKey}`);

  // 6. Return 200 OK to acknowledge receipt
  res.status(200).send("Lead processed successfully");
});

Idempotency

Store the X-Vikk-Idempotency-Key value and skip processing if you have already handled the same key. The format is webhook-leadId-timestamp.

Responses and retries

Return a 2xx status to acknowledge receipt. Non-2xx responses or timeouts may trigger retries; keep your handler lightweight and queue any heavy processing asynchronously.

Testing

Use the Vikk AI Ad Center webhook configuration panel to send test events and inspect delivery attempts before enabling live lead forwarding.

PreviousLawmatics NextIntegrations overview