Create Webhook

Creates a new webhook endpoint that will receive event notifications

POST /webhooks

Create Webhook

cURL

curl --request POST \
  --url https://api.kakiyo.com/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "CRM Integration",
  "url": "https://your-app.com/kakiyo/webhook",
  "events": [
    "linkedin.message.received",
    "prospect.qualification.manual"
  ],
  "secret": "your_webhook_secret"
}
'

201

{
  "id": "webhook_12345abcde",
  "name": "CRM Integration",
  "url": "https://your-app.com/kakiyo/webhook",
  "events": [
    "linkedin.message.received",
    "prospect.qualification.manual"
  ],
  "active": true,
  "message": "Webhook created successfully"
}

Overview

Register a webhook endpoint to receive real-time notifications about events in your Kakiyo campaigns. Webhooks enable seamless integration with your CRM, analytics tools, and custom applications.

Use Cases

• CRM Integration: Sync qualified prospects to your CRM automatically
• Analytics Tracking: Send campaign events to analytics platforms
• Notification Systems: Alert team members about important events
• Workflow Automation: Trigger automated workflows based on prospect actions

Supported Events

• prospect.qualified - Prospect marked as qualified
• prospect.responded - Prospect responded to outreach
• campaign.completed - Campaign reached completion
• message.sent - Message sent to prospect
• connection.accepted - LinkedIn connection accepted
• agent.status_changed - Agent status changed

Security

Webhooks support optional secret-based authentication. Include a secret to verify webhook authenticity using HMAC-SHA256 signatures.

Testing Example

curl -X POST "https://api.kakiyo.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Integration",
    "url": "https://your-app.com/kakiyo/webhook",
    "secret": "your_webhook_secret_key",
    "events": [
      "prospect.qualified",
      "prospect.responded",
      "campaign.completed"
    ]
  }'

// JavaScript/Node.js
const createWebhook = async (webhookData) => {
  const response = await fetch('https://api.kakiyo.com/v1/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(webhookData)
  });

  return await response.json();
};

// Usage example
const newWebhook = await createWebhook({
  name: 'CRM Integration',
  url: 'https://your-app.com/kakiyo/webhook',
  secret: 'your_webhook_secret_key',
  events: [
    'prospect.qualified',
    'prospect.responded',
    'campaign.completed'
  ]
});

console.log('Webhook Created:', newWebhook);

# Python
import requests

def create_webhook(webhook_data):
    """Create a new webhook endpoint"""
    response = requests.post(
        'https://api.kakiyo.com/v1/webhooks',
        json=webhook_data,
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        }
    )

    return response.json()

# Usage example
webhook_data = {
    'name': 'CRM Integration',
    'url': 'https://your-app.com/kakiyo/webhook',
    'secret': 'your_webhook_secret_key',
    'events': [
        'prospect.qualified',
        'prospect.responded',
        'campaign.completed'
    ]
}

result = create_webhook(webhook_data)
print('Webhook Created:', result)

Webhook Handler Example

// Express.js webhook handler
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/kakiyo/webhook', (req, res) => {
  const signature = req.headers['x-kakiyo-signature'];
  const payload = JSON.stringify(req.body);
  const secret = 'your_webhook_secret_key';

  // Verify signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (signature !== `sha256=${expectedSignature}`) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook event
  const { event, data, timestamp } = req.body;

  switch (event) {
    case 'prospect.qualified':
      handleProspectQualified(data);
      break;
    case 'prospect.responded':
      handleProspectResponded(data);
      break;
    case 'campaign.completed':
      handleCampaignCompleted(data);
      break;
    default:
      console.log(`Unhandled event: ${event}`);
  }

  res.status(200).send('OK');
});

const handleProspectQualified = (data) => {
  // Sync to CRM
  console.log('Qualified prospect:', data.prospect.name);
  // Add your CRM integration logic here
};

Best Practices

1. HTTPS Only: Always use HTTPS URLs for webhook endpoints
2. Signature Verification: Implement signature verification for security
3. Idempotency: Handle duplicate webhook deliveries gracefully
4. Error Handling: Return appropriate HTTP status codes
5. Timeout Handling: Respond within 30 seconds to avoid retries
6. Event Filtering: Subscribe only to events you need

Testing Your Webhook

Use the webhook test endpoints to validate your integration:

1. Get Available Events: GET /webhooks/test/events
2. Get Event Examples: GET /webhooks/test/example/{event}
3. Send Test Event: POST /webhooks/test

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Webhook to create

name · string · required

Example:

"CRM Integration"

url · string<uri> · required

Example:

"https://your-app.com/kakiyo/webhook"

events · enum<string>[] · required

Available options: *, linkedin.message.sent, linkedin.message.received, linkedin.invitation.sent, linkedin.invitation.accepted, prospect.qualification.manual, prospect.unqualified

Example:

[
  "linkedin.message.received",
  "prospect.qualification.manual"
]

secret · string

Example:

"your_webhook_secret"

Response

201

application/json

Webhook created successfully

id · string

Example:

"webhook_12345abcde"

name · string

Example:

"CRM Integration"

url · string

Example:

"https://your-app.com/kakiyo/webhook"

events · string[]

Example:

[
  "linkedin.message.received",
  "prospect.qualification.manual"
]

active · boolean

Example:

true

message · string

Example:

"Webhook created successfully"