Webhooks

What are webhooks?

Webhooks is a mechanism that allows your applications to receive real-time updates on events that occur during a flow session. Instead of constantly polling our API for updates, webhooks send notifications to your application when certain events occur, allowing you to create responsive and event-driven integrations.

Advantages of using webhooks

• Real-time update: Instant receive of notifications in case of event action
• API load decrease: Eliminate of the need for constant polling
• Reliable delivery: Repeating tries in case of error at sending message
• Event-driven architecture: Creating responsive applications that react to events as they occur
• Automation of working processes: Running automated processes based on specific events

Webhook set up

To set up webhooks, follow next steps:

1. Go to section Flow List in Personal Dashboard
2. Choose flow, which you want to set up
3. Press on settings of flow
4. In the webhooks section you can:
5. Add new URL-address of webhooks (not more than 5 for a flow)
6. Refresh existing configurations of webhooks
7. Delete webhooks
8. Test endpoints of webhooks

Example of webhook implementation

FastAPINode.js/Express

from fastapi import FastAPI, Request, HTTPException
import logging
from typing import Dict, Any

app = FastAPI()
logger = logging.getLogger(__name__)

async def handle_flow_start(payload: Dict[str, Any]):
    """Handling of the flow start event"""
    logger.info(f"Flow has started: {payload['session_id']}")
    # Add your business logic here

async def handle_flow_end(payload: Dict[str, Any]):
    """Handling of the flow end event"""
    logger.info(f"Flow has ended: {payload['session_id']}")
    # Add your business logic here

async def handle_technology_start(payload: Dict[str, Any]):
    """Handling of the technology start event"""
    logger.info(f"Technology has started: {payload['data']['technology_code']}")
    # Add your business logic here

async def handle_technology_end(payload: Dict[str, Any]):
    """Handling of the technology end event"""
    logger.info(f"Technology has ended: {payload['data']['technology_code']}")
    # Add your business logic here

@app.post("/webhook")
async def webhook_handler(request: Request):
    try:
        payload = await request.json()

        # Extraction of key information
        event_type = payload.get('event')
        session_id = payload.get('session_id')

        # Handling different types of events
        if event_type == 'flow.start':
            await handle_flow_start(payload)
        elif event_type == 'flow.end':
            await handle_flow_end(payload)
        elif event_type == 'technology.start':
            await handle_technology_start(payload)
        elif event_type == 'technology.end':
            await handle_technology_end(payload)

        return {"status": "success"}

    except Exception as e:
        logger.error(f"Webhook processing error: {str(e)}")
        raise HTTPException(status_code=500, detail=str(e))

const express = require('express');
const router = express.Router();

router.post('/webhook', express.json(), async (req, res) => {
    try {
        const payload = req.body;
        const eventType = payload.event;
        const sessionId = payload.session_id;

        console.log(`Event ${eventType} received for flow session: ${sessionId}`);

        switch (eventType) {
            case 'flow.start':
                await handleFlowStart(payload);
                break;
            case 'flow.end':
                await handleFlowEnd(payload);
                break;
            case 'technology.start':
                await handleTechnologyStart(payload);
                break;
            case 'technology.end':
                await handleTechnologyEnd(payload);
                break;
        }

        res.status(200).send('OK');
    } catch (error) {
        console.error('Webhook processing error:', error);
        res.status(500).send('Internal server error');
    }
});

module.exports = router;

Webhook Data

Every webhook contains next fields:

Field	Type	Description
id	string	Unique identifier of the webhook event
event	string	Event type (flow.start, flow.end, technology.start, technology.end)
session_id	string	Flow session identifier
created	number	Timestamp of event creation (in Unix timestamp format)
success	boolean	Success status of event
flow_name	string	Flow name
metadata	object	Additional metadata (if they were passed in flow session creation)
data	object	Event data (depends on event type)