Create Next App

Webhooks Overview

Receive real-time HTTP notifications when events occur in your CognexiaAI account

Quick Start

1. Create Webhook Endpoint

// Express.js example
app.post('/webhook', express.json(), (req, res) => {
  const event = req.body;
  
  console.log('Event received:', event.type);
  console.log('Event data:', event.data);
  
  // Process the event
  processEvent(event);
  
  // Respond quickly (within 5 seconds)
  res.status(200).send('OK');
});

2. Register Webhook

curl -X POST https://api.cognexiaai.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhook",
    "events": ["contact.created", "deal.closed"],
    "description": "Production webhook"
  }'

3. Verify Signatures

const crypto = require('crypto');

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

Event Types

CRM Events

contact.created, contact.updated, deal.created, deal.closed

Finance Events

invoice.created, invoice.paid, payment.received

HR Events

employee.created, attendance.logged, payroll.processed

Complete Implementation Example

const express = require('express');
const crypto = require('crypto');
const app = express();

// Webhook endpoint
app.post('/webhook', 
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-cognexia-signature'];
    const secret = process.env.WEBHOOK_SECRET;
    
    // Verify signature
    const isValid = verifySignature(
      req.body, 
      signature, 
      secret
    );
    
    if (!isValid) {
      return res.status(401).send('Invalid signature');
    }
    
    const event = JSON.parse(req.body);
    
    // Process event asynchronously
    processEventAsync(event).catch(console.error);
    
    // Respond immediately
    res.status(200).send('OK');
  }
);

async function processEventAsync(event) {
  switch (event.type) {
    case 'contact.created':
      await handleContactCreated(event.data);
      break;
    case 'deal.closed':
      await handleDealClosed(event.data);
      break;
    default:
      console.log('Unhandled event:', event.type);
  }
}

app.listen(3000);

Best Practices

Respond Quickly

Return 200 within 5 seconds, process asynchronously

Idempotency

Use event ID to prevent duplicate processing

Retry Logic

We retry up to 3 times with exponential backoff

Testing Webhooks

Use ngrok or similar to expose local endpoint
Register test webhook URL in sandbox environment
Trigger test events from dashboard
Verify payload structure and signature validation
Test error handling and retry logic

# Expose local server with ngrok
ngrok http 3000

# Register webhook with ngrok URL
curl -X POST https://api.cognexiaai.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"url": "https://abc123.ngrok.io/webhook"}'

Next Steps

Full Documentation →

Complete webhook guide

Verify Signatures →

Security guide

CLI Tools →

Manage webhooks

Webhooks Implementation