Webhooks Setup

Use Slokoto Webhooks to receive real-time HTTP POST notifications whenever leads are created, updated, or change status in your workspace.

What webhooks do

Instead of polling the API to check for changes, webhooks push events to your application the moment they happen. When a lead is created, updated, assigned, or changes status, Slokoto sends an HTTP POST request to your configured endpoint with the event details.

Use cases:

• Sync leads to an external CRM when they are created or updated
• Trigger Slack notifications when high-value leads come in
• Update dashboards in real time
• Kick off automations in Zapier, Make, or custom workflows

Available events

Create a webhook endpoint

1. Open your Slokoto dashboard
2. Click Integrations in the sidebar
3. Scroll to the Custom category
4. Click Manage on the Webhooks card
5. Click Add Webhook Endpoint
6. Enter your endpoint URL (must be HTTPS in production; http://localhost is allowed for testing)
7. Optionally add a description (e.g., "Production CRM sync")
8. Select the events you want to receive
9. Click Create Endpoint

You will see your Signing Secret. This is only shown once — copy and store it securely. You will need it to verify that incoming requests are genuinely from Slokoto.

Payload format

Every webhook delivery sends a JSON POST request with this structure:

{
  "event": "lead.created",
  "created_at": "2026-03-19T14:30:00Z",
  "data": {
    "lead": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "john@acme.com",
      "name": "John Smith",
      "company": "Acme Corp",
      "status": "active",
      "deal_value": 5000000,
      "tags": ["enterprise"],
      "created_at": "2026-03-19T14:30:00Z",
      "updated_at": "2026-03-19T14:30:00Z"
    }
  }
}

For lead.updated and lead.status_changed events, the payload also includes a changes object showing what changed:

{
  "event": "lead.status_changed",
  "created_at": "2026-03-19T15:00:00Z",
  "data": {
    "lead": { ... },
    "changes": {
      "status": { "from": "active", "to": "won" }
    }
  }
}

Request headers

Every webhook request includes these headers:

Verifying signatures

Every webhook is signed using your endpoint's signing secret. Always verify the signature to ensure the request is genuinely from Slokoto.

The X-Slokoto-Signature header has the format: t=,v1=

Node.js example

const crypto = require('crypto');

function verifyWebhook(payload, signatureHeader, secret) {
  const parts = signatureHeader.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).slice(2);
  const signature = parts.find(p => p.startsWith('v1=')).slice(3);

  // Check timestamp is within 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error('Webhook timestamp too old');
  }

  // Compute expected signature
  const signedContent = timestamp + '.' + payload;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedContent)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

Python example

import hmac
import hashlib
import time

def verify_webhook(payload: str, signature_header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in signature_header.split(','))
    timestamp = parts['t']
    signature = parts['v1']

    # Check timestamp tolerance (5 minutes)
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError('Webhook timestamp too old')

    # Compute expected signature
    signed = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode(), signed.encode(), hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Testing your endpoint

Before going live, use the Send Test Ping button to verify your endpoint is reachable:

1. Go to Integrations → Custom → Webhooks
2. Find your endpoint and click the send icon
3. Slokoto will send a ping event to your endpoint
4. Check the delivery log to see if it was delivered successfully

Retry policy

If your endpoint returns a non-2xx status code or times out (10-second limit), Slokoto retries with exponential backoff:

After 5 failed attempts, the delivery is marked as permanently failed. You can see all delivery attempts in the delivery log.

Monitoring deliveries

Click the expand arrow on any webhook endpoint to view its recent delivery log. Each entry shows:

• Event type — what triggered the delivery
• Status — delivered, retrying, or failed
• HTTP status — the response code from your endpoint
• Attempt count — how many delivery attempts were made
• Timestamp — when the delivery was attempted

Managing endpoints

Pause an endpoint

Click the Active/Inactive toggle on any endpoint to temporarily pause deliveries without deleting the endpoint.

Delete an endpoint

Click the trash icon to permanently remove an endpoint. All pending retries for that endpoint will be cancelled.

Full reference

For complete webhook documentation including all event payload shapes, visit the [Webhooks section of the API Documentation](/developers#webhooks).