⚡ Don't miss the limited time deal !

04:57:49
Documentation/Universal Webhooks API
Developer Reference • Webhooks API v1
|HMAC-SHA256 Signed700+ Compatible Platforms

Universal Webhooks Engine

Receive instant, cryptographically verified HTTP notifications whenever an AI sales agent captures a lead, answers high-intent inquiries, or completes conversations. Seamlessly automate workflows in Zapier, Make, Activepieces, HubSpot, Slack, or your custom internal APIs.

Webhook Architecture
ProtocolHTTPS POST
Payload Formatapplication/json
Signing MethodHMAC-SHA256
Delivery Timeout10 Seconds
Retry Policy3x Exponential Backoff
Open Integration Settings
1

3-Minute Quick Start

Configure and test your first webhook in three simple steps.

Step 1

Create Endpoint

Navigate to Agent Dashboard → Integration → Universal Webhooks. Click New Endpoint and input your public HTTPS URL (or webhook URL from Zapier/Make).

Step 2

Subscribe to Events

Choose the event types you want to receive, like lead.created or select All Events to stream the full conversational lifecycle.

Step 3

Verify & Test Ping

Copy your unique signing secret (whsec_...) for HMAC verification, then click Test Ping to verify live delivery in real time.

2

HTTP Headers Specification

Every webhook POST request from Talk2Site includes standardized security and tracing headers.

HeaderTypeSecurity & Idempotency RoleExample Value
X-Talk2Site-Signature
stringSecurity Critical

HMAC-SHA256 signature generated with your webhook secret. Verify this before accepting any payload.

sha256=d3b07384d113edec...
X-Talk2Site-Event
stringRouting

The event type being sent (lead.created, conversation.ended, ping).

lead.created
X-Talk2Site-Delivery
uuidIdempotency Key

Unique UUID per dispatch attempt. Store this in your database to prevent duplicate processing on retries.

9f8b7c2a-4e1d-48a6-9f12-09b7c84ef3d1
X-Talk2Site-Timestamp
integerReplay Protection

Unix epoch timestamp (seconds). Discard incoming requests older than 300 seconds to thwart replay attacks.

1789210530
Content-TypestringMIME type of the request payload body.application/json
3

Event Catalog & JSON Payloads

Explore complete JSON schemas and field definitions for each webhook event.

High IntentEvent: lead.created

Lead Created

Fires immediately when an AI agent captures visitor contact information (name, email, phone, custom fields, and inquiry context).

Trigger Condition: Visitor submits contact info or the conversational agent qualifies a prospect.
Field Schema Definitions
eventstring

Always 'lead.created'

timestampISO-8601 string

UTC timestamp when event occurred

agent_idinteger

The ID of the agent that captured the lead

agent_namestring

The public name of the agent

data.lead_idinteger

Unique lead ID in Talk2Site

data.namestring

Prospect's name

data.emailstring

Prospect's verified email address

data.phonestring

Prospect's phone number (if provided)

data.chat_summarystring

AI-generated executive summary of the conversation

data.custom_fieldsobject

Key-value pairs collected by the qualification funnel

data.page_urlstring

Exact website page where the conversation took place

{
  "event": "lead.created",
  "timestamp": "2026-09-12T10:15:30Z",
  "agent_id": 42,
  "agent_name": "My Sales Assistant",
  "data": {
    "lead_id": 1084,
    "name": "Alex Rivera",
    "email": "alex.rivera@example.com",
    "phone": "+1 (555) 234-5678",
    "chat_summary": "Inquired about enterprise SLA, pricing tiers, and multi-agent deployment.",
    "custom_fields": {
      "company_size": "50-200",
      "budget": "$5,000/yr"
    },
    "page_url": "https://mysite.com/pricing",
    "created_at": "2026-09-12T10:15:28Z"
  }
}
4

Verifying Signatures (HMAC-SHA256)

Prevent spoofing and replay attacks by validating signatures using your secret key.

Raw Body Required

Always compute the HMAC hash using the raw, unparsed request bytes. Frameworks that re-serialize parsed JSON may alter whitespace, causing verification to fail.

Constant-Time Compare

Use constant-time comparison methods (crypto.timingSafeEqual, hmac.compare_digest) to eliminate side-channel timing vulnerabilities.

Replay Validation

Check the X-Talk2Site-Timestamp header. Reject payloads older than 5 minutes to prevent malicious attackers from replaying captured requests.

// Node.js (Express)
import express from 'express';
import crypto from 'crypto';

const app = express();
const WEBHOOK_SECRET = process.env.TALK2SITE_WEBHOOK_SECRET; // e.g. "whsec_..."

// Capture raw body buffer for signature verification
app.post('/api/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-talk2site-signature'];
  if (!signature) {
    return res.status(401).send('Missing X-Talk2Site-Signature header');
  }

  // Compute expected HMAC-SHA256
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  const digest = 'sha256=' + hmac.update(req.body).digest('hex');

  // Secure constant-time comparison to prevent timing attacks
  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.body.toString('utf8'));
  console.log('Verified Talk2Site event:', payload.event);

  if (payload.event === 'lead.created') {
    const lead = payload.data;
    console.log('New lead captured:', lead.name, lead.email);
    // Forward to CRM (HubSpot, Salesforce, Slack, etc.)
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Webhook receiver running on port 3000'));
5

Delivery Guarantees & Retry Schedule

Robust delivery guarantees ensure zero lost leads or customer inquiries during transient server downtime.

Success Code

HTTP 2xx

Any status code between 200 and 299 confirms receipt and stops retries.

Timeout Limit

10 Seconds

Endpoints must respond within 10s. Queue long-running tasks asynchronously and return HTTP 200 immediately.

Retry Schedule

3x Backoff

Automatic exponential retries: Immediate, followed by 30s, then 2m before logging failure.

Deduplication

Delivery ID

Use the X-Talk2Site-Delivery UUID as an idempotency key to prevent double processing.

6

Connecting to Zapier, Make & Activepieces

Connect Talk2Site webhooks to 700+ SaaS apps without writing a single line of code.

Z
5,000+ Apps

Zapier “Catch Hook”

  1. Create a new Zap and choose Webhooks by Zapier as the trigger.
  2. Select the Catch Hook event and copy the generated Webhook URL.
  3. Paste the URL into your Talk2Site Universal Webhooks settings and click Test Ping.
  4. Zapier will detect the test payload. Map email and name directly to your CRM.
M
Visual Flows

Make (Integromat)

  1. Create a scenario and add the Custom Webhook module.
  2. Copy the generated webhook URL into Talk2Site webhook endpoints.
  3. Trigger a Test Ping in Talk2Site so Make determines the JSON data structure.
  4. Branch and route lead notifications to Slack, Google Sheets, or HubSpot.
A
Self-Hosted / Cloud

Activepieces & n8n

  1. Add the Catch Webhook piece to your workflow canvas.
  2. Set the HTTP Method to POST and copy the test address.
  3. Paste the webhook address into Talk2Site agent integration settings.
  4. Sync customer information with self-hosted PostgreSQL, ERPs, or custom apps.
Ready to Automate?

Configure Webhooks on Your Agent Now

Add destination endpoints, copy your HMAC signing secret, and inspect live delivery logs directly from your agent dashboard.

Go to Integration Settings

We use essential cookies and performance analytics to ensure secure login and improve your AI chatbot experience. By using Talk2Site, you agree to our Cookie Policy.