Webhooks

Webhooks

Webhooks notify your external systems in real time when events occur in Skode. Instead of polling the API for changes, register a webhook URL and Skode will send an HTTP POST request with event data whenever a subscribed event fires.

Creating a Webhook

Navigate to Settings > API & Webhooks > Webhooks and click + Add Webhook. Provide a destination URL (HTTPS required), select the events you want to subscribe to, and optionally set a secret key for signature verification.

curl -X POST "https://api.skode.ai/v1/webhooks" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/skode",
    "events": ["lead.created", "lead.updated", "deal.stage_changed", "deal.closed"],
    "secret": "whsec_your_signing_secret"
  }'

Available Events

• lead.created, lead.updated, lead.deleted, lead.assigned
• deal.created, deal.updated, deal.stage_changed, deal.closed
• contact.created, contact.updated, contact.deleted, contact.merged
• invoice.created, invoice.sent, invoice.paid, invoice.overdue
• task.created, task.completed, task.overdue
• message.received, message.sent, conversation.assigned

Payload Format

{
  "id": "evt_abc123",
  "event": "lead.created",
  "created_at": "2026-03-15T10:30:00Z",
  "data": {
    "id": "lead_xyz789",
    "name": "John Smith",
    "email": "john@example.com",
    "company": "Example Corp",
    "source": "website",
    "created_at": "2026-03-15T10:30:00Z"
  }
}

Signature Verification

If you set a secret key, Skode includes an X-Skode-Signature header with each delivery. Verify it using HMAC-SHA256:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Logic

If your endpoint returns a non-2xx status code or times out (30 seconds), Skode retries the delivery using exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, and 24 hours. After 5 failed attempts, the webhook is marked as failing and you receive an email notification. Fix the issue and re-enable the webhook from the settings page.

Webhook Logs

View delivery history for each webhook under Settings > Webhooks > Logs. Each log entry shows the event type, payload, response status code, response body, and delivery duration. Use logs to debug integration issues and verify payloads.