Webhook Setup Guide

Prerequisites

Before setting up webhooks, make sure you have:

• Dashboard Access: You need access to deepsy.fr/dashboard
• HTTPS Endpoint: A publicly accessible HTTPS URL to receive webhook events (or a tunneling solution like ngrok for testing)

Step 1: Create Your Webhook in the Dashboard

Head over to the webhook section in your user settings at deepsy.fr/dashboard/user/webhooks

You'll see a Create button there. Click it and you'll be able to:

• Give your webhook a name and description
• Set the URL where you want to receive events
• Choose which events you want to subscribe to
• Select which companies you want to monitor

---

If you're not an administrator of the companies you selected, someone with admin permissions needs to authorize your webhook. They'll need to go to Company Settings → Webhooks and approve your webhook request.

---

Step 2: Create Your Webhook Endpoint

Now you need to create an endpoint in your application to receive webhook events. Here are examples in different languages:

JavaScript

const http = require('http');
const url = require('url');

const PORT = 1234;

const server = http.createServer((req, res) => {
    const timestamp = new Date().toISOString();
    const method = req.method;
    const requestUrl = req.url;
    const headers = req.headers;

    console.log('\n' + '='.repeat(80));
    console.log(`[${timestamp}] Incoming ${method} request to ${requestUrl}`);
    console.log('='.repeat(80));

    // Log headers
    console.log('\n📋 HEADERS:');
    console.log('-'.repeat(40));
    Object.entries(headers).forEach(([key, value]) => {
        console.log(`${key}: ${value}`);
    });

    // Collect request body
    let body = '';
    req.on('data', chunk => {
        body += chunk.toString();
    });

    req.on('end', () => {
        // Log request body
        console.log('\n📦 REQUEST BODY:');
        console.log('-'.repeat(40));
        if (body) {
            try {
                // Try to pretty-print JSON
                const jsonBody = JSON.parse(body);
                console.log(JSON.stringify(jsonBody, null, 2));
            } catch (e) {
                // If not JSON, log as plain text
                console.log(body);
            }
        } else {
            console.log('(empty body)');
        }

        // Log query parameters if any
        const parsedUrl = url.parse(requestUrl, true);
        if (Object.keys(parsedUrl.query).length > 0) {
            console.log('\n🔍 QUERY PARAMETERS:');
            console.log('-'.repeat(40));
            Object.entries(parsedUrl.query).forEach(([key, value]) => {
                console.log(`${key}: ${value}`);
            });
        }

        console.log('\n' + '='.repeat(80));

        // Send response
        res.writeHead(200, {
            'Content-Type': 'application/json',
            'Access-Control-Allow-Origin': '*',
            'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
            'Access-Control-Allow-Headers': 'Content-Type, Authorization'
        });

        res.end(JSON.stringify({
            status: 'success',
            message: 'Webhook received successfully',
            timestamp: timestamp,
            method: method,
            url: requestUrl
        }, null, 2));
    });
});

// Handle OPTIONS requests for CORS
server.on('request', (req, res) => {
    if (req.method === 'OPTIONS') {
        res.writeHead(200, {
            'Access-Control-Allow-Origin': '*',
            'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
            'Access-Control-Allow-Headers': 'Content-Type, Authorization'
        });
        res.end();
    }
});

server.listen(PORT, 'localhost', () => {
    console.log(`🚀 Webhook server running on http://localhost:${PORT}`);
    console.log('📡 Ready to receive webhook requests...');
    console.log('Press Ctrl+C to stop the server\n');
});

// Graceful shutdown
process.on('SIGINT', () => {
    console.log('\n\n🛑 Shutting down webhook server...');
    server.close(() => {
        console.log('✅ Server closed successfully');
        process.exit(0);
    });
});

TypeScript

import * as http from 'http';
import * as url from 'url';

interface WebhookPayload {
    event: string;
    webhook_id: string;
    timestamp: string;
    company_id: string;
    data: any;
}

const PORT = 1234;

const server = http.createServer((req: http.IncomingMessage, res: http.ServerResponse) => {
    const timestamp = new Date().toISOString();
    const method = req.method;
    const requestUrl = req.url;
    const headers = req.headers;

    console.log('\n' + '='.repeat(80));
    console.log(`[${timestamp}] Incoming ${method} request to ${requestUrl}`);
    console.log('='.repeat(80));

    // Log headers
    console.log('\n📋 HEADERS:');
    console.log('-'.repeat(40));
    Object.entries(headers).forEach(([key, value]) => {
        console.log(`${key}: ${value}`);
    });

    // Collect request body
    let body = '';
    req.on('data', (chunk: Buffer) => {
        body += chunk.toString();
    });

    req.on('end', () => {
        // Log request body
        console.log('\n📦 REQUEST BODY:');
        console.log('-'.repeat(40));
        if (body) {
            try {
                // Try to pretty-print JSON
                const jsonBody: WebhookPayload = JSON.parse(body);
                console.log(JSON.stringify(jsonBody, null, 2));
            } catch (e) {
                // If not JSON, log as plain text
                console.log(body);
            }
        } else {
            console.log('(empty body)');
        }

        // Log query parameters if any
        const parsedUrl = url.parse(requestUrl || '', true);
        if (Object.keys(parsedUrl.query).length > 0) {
            console.log('\n🔍 QUERY PARAMETERS:');
            console.log('-'.repeat(40));
            Object.entries(parsedUrl.query).forEach(([key, value]) => {
                console.log(`${key}: ${value}`);
            });
        }

        console.log('\n' + '='.repeat(80));

        // Send response
        res.writeHead(200, {
            'Content-Type': 'application/json',
            'Access-Control-Allow-Origin': '*',
            'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
            'Access-Control-Allow-Headers': 'Content-Type, Authorization'
        });

        res.end(JSON.stringify({
            status: 'success',
            message: 'Webhook received successfully',
            timestamp: timestamp,
            method: method,
            url: requestUrl
        }, null, 2));
    });
});

server.listen(PORT, 'localhost', () => {
    console.log(`🚀 Webhook server running on http://localhost:${PORT}`);
    console.log('📡 Ready to receive webhook requests...');
    console.log('Press Ctrl+C to stop the server\n');
});

// Graceful shutdown
process.on('SIGINT', () => {
    console.log('\n\n🛑 Shutting down webhook server...');
    server.close(() => {
        console.log('✅ Server closed successfully');
        process.exit(0);
    });
});

PHP

<?php
$port = 1234;

// Create a socket
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
socket_set_option($socket, SOL_SOCKET, SO_REUSEADDR, 1);
socket_bind($socket, 'localhost', $port);
socket_listen($socket);

echo "🚀 Webhook server running on http://localhost:$port\n";
echo "📡 Ready to receive webhook requests...\n";
echo "Press Ctrl+C to stop the server\n\n";

while (true) {
    $client = socket_accept($socket);

    if ($client === false) {
        continue;
    }

    $request = socket_read($client, 2048);
    $timestamp = date('c');

    echo str_repeat('=', 80) . "\n";
    echo "[$timestamp] Incoming request\n";
    echo str_repeat('=', 80) . "\n";

    // Parse HTTP request
    $lines = explode("\n", $request);
    $firstLine = $lines[0];
    $method = explode(' ', $firstLine)[0];
    $path = explode(' ', $firstLine)[1];

    echo "\n📋 REQUEST INFO:\n";
    echo str_repeat('-', 40) . "\n";
    echo "Method: $method\n";
    echo "Path: $path\n";

    // Find headers and body
    $headerEnd = strpos($request, "\r\n\r\n");
    if ($headerEnd !== false) {
        $headers = substr($request, 0, $headerEnd);
        $body = substr($request, $headerEnd + 4);

        echo "\n📋 HEADERS:\n";
        echo str_repeat('-', 40) . "\n";
        $headerLines = explode("\n", $headers);
        foreach ($headerLines as $line) {
            if (trim($line) && !strpos($line, 'HTTP/')) {
                echo trim($line) . "\n";
            }
        }

        echo "\n📦 REQUEST BODY:\n";
        echo str_repeat('-', 40) . "\n";
        if (trim($body)) {
            $jsonData = json_decode($body, true);
            if ($jsonData) {
                echo json_encode($jsonData, JSON_PRETTY_PRINT) . "\n";
            } else {
                echo $body . "\n";
            }
        } else {
            echo "(empty body)\n";
        }
    }

    echo "\n" . str_repeat('=', 80) . "\n";

    // Send HTTP response
    $response = "HTTP/1.1 200 OK\r\n";
    $response .= "Content-Type: application/json\r\n";
    $response .= "Access-Control-Allow-Origin: *\r\n";
    $response .= "Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\r\n";
    $response .= "Access-Control-Allow-Headers: Content-Type, Authorization\r\n";
    $response .= "Connection: close\r\n\r\n";

    $responseBody = json_encode([
        'status' => 'success',
        'message' => 'Webhook received successfully',
        'timestamp' => $timestamp,
        'method' => $method,
        'path' => $path
    ], JSON_PRETTY_PRINT);

    $response .= $responseBody;

    socket_write($client, $response);
    socket_close($client);
}

socket_close($socket);
?>

Python

import http.server
import socketserver
import json
import urllib.parse
from datetime import datetime

PORT = 1234

class WebhookHandler(http.server.BaseHTTPRequestHandler):
    def do_POST(self):
        self.handle_request('POST')

    def do_GET(self):
        self.handle_request('GET')

    def do_OPTIONS(self):
        self.send_response(200)
        self.send_header('Access-Control-Allow-Origin', '*')
        self.send_header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
        self.send_header('Access-Control-Allow-Headers', 'Content-Type, Authorization')
        self.end_headers()

    def handle_request(self, method):
        timestamp = datetime.now().isoformat()

        print('\n' + '=' * 80)
        print(f'[{timestamp}] Incoming {method} request to {self.path}')
        print('=' * 80)

        # Log headers
        print('\n📋 HEADERS:')
        print('-' * 40)
        for header, value in self.headers.items():
            print(f'{header}: {value}')

        # Read and log body
        content_length = int(self.headers.get('Content-Length', 0))
        body = self.rfile.read(content_length).decode('utf-8') if content_length > 0 else ''

        print('\n📦 REQUEST BODY:')
        print('-' * 40)
        if body:
            try:
                json_body = json.loads(body)
                print(json.dumps(json_body, indent=2))
            except json.JSONDecodeError:
                print(body)
        else:
            print('(empty body)')

        # Log query parameters
        parsed_url = urllib.parse.urlparse(self.path)
        query_params = urllib.parse.parse_qs(parsed_url.query)
        if query_params:
            print('\n🔍 QUERY PARAMETERS:')
            print('-' * 40)
            for key, values in query_params.items():
                print(f'{key}: {", ".join(values)}')

        print('\n' + '=' * 80)

        # Send response
        self.send_response(200)
        self.send_header('Content-Type', 'application/json')
        self.send_header('Access-Control-Allow-Origin', '*')
        self.send_header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
        self.send_header('Access-Control-Allow-Headers', 'Content-Type, Authorization')
        self.end_headers()

        response_data = {
            'status': 'success',
            'message': 'Webhook received successfully',
            'timestamp': timestamp,
            'method': method,
            'url': self.path
        }

        self.wfile.write(json.dumps(response_data, indent=2).encode('utf-8'))

with socketserver.TCPServer(("localhost", PORT), WebhookHandler) as httpd:
    print(f"🚀 Webhook server running on http://localhost:{PORT}")
    print("📡 Ready to receive webhook requests...")
    print("Press Ctrl+C to stop the server\n")

    try:
        httpd.serve_forever()
    except KeyboardInterrupt:
        print("\n\n🛑 Shutting down webhook server...")
        httpd.shutdown()
        print("✅ Server closed successfully")

Step 3: Make Your Endpoint Publicly Accessible

Your webhook endpoint needs to be accessible from the internet. Here are some options:

Development & Testing

For development and testing, you can use tunneling services to expose your local server:

ngrok (Recommended)

ngrok provides reliable tunneling with HTTPS support:

# Install ngrok and create a tunnel to your local server
ngrok http 1234

This gives you a public HTTPS URL like https://abc123.ngrok.io that forwards to your local server.

serveo (Free Alternative)

serveo is a free alternative, though it can be unstable:

# Create a tunnel using SSH
ssh -R 80:localhost:1234 serveo.net

serveo Stability

serveo is incredibly unstable compared to ngrok. While it's free, ngrok provides a much better and more reliable service.

For production use, always use ngrok or deploy to a proper hosting service. For development and testing, serveo is more than enough.

Learn more about serveo at serveo.net and their tutorial blog.

CLI Tool Alternative

If you'd prefer a CLI tool to test webhooks without using tunneling services, tell us about it at dev@deepsy.fr, we might create one.

Step 4: Company Authorization

After creating a webhook, company administrators must authorize it:

Dashboard Authorization

Company administrators need to go to Company Settings → Webhooks (deepsy.fr/dashboard/company/settings/webhooks) and authorize your webhook request.

If all companies refuse your webhook, it will be automatically deleted.

You'll receive notifications in your dashboard about authorization status.

---

Step 5: Test Your Webhook

Once your webhook is authorized, you can test it directly from the dashboard. Click on your webhook and use the test feature to send sample events.

The test will show you both the request payload sent to your endpoint and the response your server returned.

Configuration Options

When creating webhooks, you can configure:

Required Settings

• Name: Human-readable name for your webhook
• URL: HTTPS endpoint URL to receive events
• Events: Which event types you want to subscribe to
• Companies: Which companies you want to monitor

Optional Settings

• Description: Detailed description of the webhook's purpose
• Signature Verification: Enable HMAC signature verification (recommended)
• Max Retries: Number of retry attempts for failed deliveries (0-5)
• Metadata: Custom key-value pairs for your reference

Best Practices

Endpoint Design

1. Always Return 200: Return HTTP 200 for successful processing
2. Process Quickly: Handle events quickly to avoid timeouts (30-second limit)
3. Handle Duplicates: Process duplicate events gracefully
4. Log Everything: Log all received events for debugging

Security

1. Use HTTPS: Webhook URLs must use HTTPS
2. Verify Signatures: Always verify webhook signatures when enabled - see our Security Guide
3. Validate Data: Validate event data before processing
4. Rate Limiting: Implement rate limiting on your webhook endpoints

Monitoring

1. Track Deliveries: Monitor webhook delivery success rates
2. Set Up Alerts: Alert on webhook endpoint failures
3. Review Logs: Regularly check webhook logs in the dashboard

Next Steps

Now that your webhook is set up:

• Learn about Available Events and their payloads
• Implement Security Verification for your webhooks
• Check out Testing Strategies for development
• Review Troubleshooting for common issues

Need Help?

If you encounter any issues:

• Check our Troubleshooting Guide for common problems
• Contact our development team at dev@deepsy.fr
• Reach out via deepsy.fr/contact