Webhooks

Webhooks allow your application to receive real-time notifications when events occur in Synaptiq. Instead of polling the API, Synaptiq sends an HTTP POST request to your configured endpoint whenever a subscribed event fires.

Setting Up Webhooks

1. Navigate to Settings > Webhooks in your Synaptiq Dashboard.
2. Click Add Endpoint.
3. Enter your HTTPS endpoint URL.
4. Select the events you want to subscribe to.
5. Click Create. Synaptiq will send a test ping to verify your endpoint.

You can also manage webhooks via the API:

curl -X POST https://synaptiqintel.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/synaptiq",
    "events": ["lead.created", "lead.qualified", "conversation.completed"],
    "secret": "whsec_your_signing_secret_here"
  }'

{
  "id": "wh_01HQ9AAA1BBB2CCC3DDD4EEE5F",
  "url": "https://your-app.com/webhooks/synaptiq",
  "events": ["lead.created", "lead.qualified", "conversation.completed"],
  "status": "active",
  "createdAt": "2026-04-05T16:00:00.000Z"
}

Event Types

Event	Description
lead.created	A new lead was captured from a conversation or the API.
lead.updated	A lead's fields were modified (status, score, tags, etc.).
lead.qualified	A lead's status changed to qualified.
lead.converted	A lead's status changed to converted.
lead.deleted	A lead was deleted.
conversation.started	A new AI conversation was initiated.
conversation.completed	A conversation was closed or expired.
conversation.handoff	A conversation was handed off to a human agent.
message.received	A new visitor message was received in a conversation.
message.sent	The AI agent sent a response message.
intent.high_value	A high-value buying intent was detected in a conversation.

Payload Structure

Every webhook delivery follows a consistent envelope format:

{
  "id": "evt_01HQAAA1BBB2CCC3DDD4EEE5FF",
  "type": "lead.created",
  "apiVersion": "2026-01-15",
  "createdAt": "2026-04-05T16:05:00.000Z",
  "data": {
    // Event-specific payload (see examples below)
  }
}

Envelope Fields

Field	Type	Description
id	string	Unique event ID. Use for idempotency checks.
type	string	The event type that triggered the webhook.
apiVersion	string	The API version used to format the payload.
createdAt	string	ISO 8601 timestamp of when the event occurred.
data	object	The event payload. Structure varies by event type.

Delivery Headers

Each webhook request includes the following headers:

Header	Description
Content-Type	Always application/json.
User-Agent	Synaptiq-Webhooks/1.0.
X-Synaptiq-Event	The event type (e.g., lead.created).
X-Synaptiq-Delivery	A unique delivery ID for this attempt.
X-Synaptiq-Timestamp	Unix timestamp (seconds) of when the request was sent.
X-Synaptiq-Signature	HMAC-SHA256 signature for verifying payload authenticity.

Verifying Signatures

Every webhook delivery is signed with your webhook secret using HMAC-SHA256. Always verify the signature before processing a webhook to ensure the request is genuinely from Synaptiq.

The signature is computed over the concatenation of the timestamp and the raw request body:

signature = HMAC-SHA256(secret, timestamp + "." + body)

Node.js Verification Example

const crypto = require("crypto");

function verifyWebhookSignature(req, secret) {
  const timestamp = req.headers["x-synaptiq-timestamp"];
  const signature = req.headers["x-synaptiq-signature"];
  const body = req.rawBody; // raw request body as string

  // Reject requests older than 5 minutes to prevent replay attacks
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - parseInt(timestamp)) > 300) {
    throw new Error("Webhook timestamp too old. Possible replay attack.");
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex");

  const trusted = Buffer.from(expected, "hex");
  const received = Buffer.from(signature, "hex");

  if (!crypto.timingSafeEqual(trusted, received)) {
    throw new Error("Invalid webhook signature.");
  }

  return true;
}

Python Verification Example

import hmac
import hashlib
import time

def verify_webhook(payload_body, timestamp, signature, secret):
    # Reject old timestamps (5-minute tolerance)
    current_time = int(time.time())
    if abs(current_time - int(timestamp)) > 300:
        raise ValueError("Webhook timestamp too old")

    expected = hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.{payload_body}".encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError("Invalid webhook signature")

    return True

Event Payload Examples

lead.created

{
  "id": "evt_01HQAAA1BBB2CCC3DDD4EEE5FF",
  "type": "lead.created",
  "apiVersion": "2026-01-15",
  "createdAt": "2026-04-05T16:05:00.000Z",
  "data": {
    "lead": {
      "id": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
      "email": "sarah.chen@acmecorp.com",
      "name": "Sarah Chen",
      "company": "Acme Corp",
      "status": "new",
      "score": 42,
      "source": "chat",
      "createdAt": "2026-04-05T16:05:00.000Z"
    },
    "conversationId": "conv_01HQ7ABC2DEF3GHI4JKL5MNO6P"
  }
}

lead.qualified

{
  "id": "evt_01HQBBB2CCC3DDD4EEE5FFF6GG",
  "type": "lead.qualified",
  "apiVersion": "2026-01-15",
  "createdAt": "2026-04-05T16:10:00.000Z",
  "data": {
    "lead": {
      "id": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
      "email": "sarah.chen@acmecorp.com",
      "name": "Sarah Chen",
      "company": "Acme Corp",
      "status": "qualified",
      "score": 87,
      "previousStatus": "new"
    },
    "qualificationReason": "High intent signals: pricing inquiry, demo request, team size confirmed (50+ seats)."
  }
}

conversation.handoff

{
  "id": "evt_01HQCCC3DDD4EEE5FFF6GGG7HH",
  "type": "conversation.handoff",
  "apiVersion": "2026-01-15",
  "createdAt": "2026-04-05T16:15:00.000Z",
  "data": {
    "conversation": {
      "id": "conv_01HQ7ABC2DEF3GHI4JKL5MNO6P",
      "leadId": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
      "messageCount": 14,
      "status": "handed_off"
    },
    "handoff": {
      "reason": "enterprise_inquiry",
      "priority": "high",
      "suggestedTeam": "enterprise-sales",
      "context": "Visitor is CTO of 50-person SaaS company comparing with Drift. Budget confirmed at $5-10k/mo."
    }
  }
}

intent.high_value

{
  "id": "evt_01HQDDD4EEE5FFF6GGG7HHH8II",
  "type": "intent.high_value",
  "apiVersion": "2026-01-15",
  "createdAt": "2026-04-05T16:20:00.000Z",
  "data": {
    "leadId": "lead_01HQ6JKL8MWPN3D5R7S9T1UVWX",
    "conversationId": "conv_01HQ7QRS8TUV9WXY0ZAB1CDE2F",
    "intent": "purchase_ready",
    "confidence": 0.92,
    "signals": [
      "Asked about contract terms",
      "Confirmed budget authority",
      "Requested implementation timeline"
    ],
    "estimatedDealSize": 18000
  }
}

Retry Behavior

If your endpoint returns a non-2xx status code or fails to respond within 30 seconds, Synaptiq retries the delivery with exponential backoff:

Attempt	Delay After Failure
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	12 hours
7 (final)	24 hours

After 7 failed attempts, the delivery is marked as failed. You can view failed deliveries and manually retry them from the Webhooks page in your dashboard.

Best Practices

• Respond quickly. Return a 200 OK as soon as you receive the webhook. Process the event asynchronously.
• Use idempotency. Store the event id and skip duplicates. Retries may deliver the same event more than once.
• Verify signatures. Always validate X-Synaptiq-Signature to prevent spoofed requests.
• Monitor delivery health. Check the webhook dashboard for failed deliveries and error rates.
• Use HTTPS. Synaptiq only delivers webhooks to HTTPS endpoints.