Skip to main content
NavTalk supports pushing real-time conversation events and complete session records to your server via Webhook, enabling you to:
  • Receive real-time session lifecycle events (session creation, message output, session closure)
  • Receive complete session records when a session ends
  • Persist conversation data to databases
  • Implement business logic processing and data analysis

How It Works

Webhook uses HTTP POST requests to push events to your configured server endpoint. NavTalk triggers Webhooks in the following scenarios:
  1. Real-time Event Push (/api/webhook/message): Immediately pushes when specific events occur in a session
  2. Session Record Push (/api/webhook/session): Pushes complete session data when a session ends

Event Types

Real-time Events (Message Webhook): Pushed through the /api/webhook/message endpoint, including the following event types:
Event TypeDescriptionTrigger Time
session.createdSession creationWhen a new session is established
conversation.outputConversation outputWhen AI or user sends a message
session.closedSession closureWhen a session ends
Session Records (Session Webhook): Pushed through the /api/webhook/session endpoint, including complete message list (all conversation content), session start time, session end time, and session ID.

Quick Start

Select your programming language and framework to create a Webhook endpoint. Below are example code snippets for Webhook controller/route handling:
package org.demo.hookjava.controller;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.demo.hookjava.model.SessionData;
import org.demo.hookjava.model.MessageData;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/webhook")
public class WebhookController {

    private static final Logger logger = LoggerFactory.getLogger(WebhookController.class);
    private final ObjectMapper objectMapper = new ObjectMapper();

    /**
     * Receive real-time Webhook events
     * Handle events such as session creation, conversation output, and session closure
     */
    @PostMapping("/message")
    public ResponseEntity<String> receiveRealTimeWebhook(@RequestBody MessageData payload) {
        logger.info("========== Webhook Event Received ==========");
        logger.info("Event: {}", payload.getEvent());
        logger.info("Session ID: {}", payload.getSessionId());
        logger.info("Role: {}", payload.getRole());
        logger.info("Timestamp: {}", payload.getTimestamp());
        logger.info("Message: {}", payload.getMessage());
        logger.info("============================================");

        // Handle business logic based on event type
        switch (payload.getEvent()) {
            case "session.created":
                // TODO: Handle session creation logic
                break;
            case "conversation.output":
                // TODO: Handle conversation messages
                break;
            case "session.closed":
                // TODO: Handle session closure logic
                break;
            default:
                logger.warn("Unknown event type: {}", payload.getEvent());
        }

        return ResponseEntity.ok("Webhook received successfully");
    }

    /**
     * Receive complete session record
     * Receive entire session data when session ends
     */
    @PostMapping("/session")
    public ResponseEntity<String> receiveSessionRecord(@RequestBody SessionData sessData) {
        try {
            String jsonStr = objectMapper.writerWithDefaultPrettyPrinter()
                    .writeValueAsString(sessData);
            logger.info("Full session record received: {}", jsonStr);
            // TODO: Persist sessData to database or perform other business logic
        } catch (Exception e) {
            logger.error("Failed to process session record", e);
        }
        return ResponseEntity.ok("Session record received successfully");
    }
}
Data model definitions:
package org.demo.hookjava.model;

public class MessageData {
    private String event;       // session.created、conversation.output、session.closed
    private String sessionId;
    private String role;        // ai、user、system
    private String timestamp;   // ISO 8601
    private String message;     // conversation.output

    // Getter / Setter
    public String getEvent() { return event; }
    public void setEvent(String event) { this.event = event; }

    public String getSessionId() { return sessionId; }
    public void setSessionId(String sessionId) { this.sessionId = sessionId; }

    public String getRole() { return role; }
    public void setRole(String role) { this.role = role; }

    public String getTimestamp() { return timestamp; }
    public void setTimestamp(String timestamp) { this.timestamp = timestamp; }

    public String getMessage() { return message; }
    public void setMessage(String message) { this.message = message; }
}
Dependency configuration files:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.demo</groupId>
    <artifactId>HookJava</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>HookJava</name>
    <description>NavTalk Webhook sample project</description>
    <properties>
        <java.version>1.8</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <spring-boot.version>2.6.13</spring-boot.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </dependency>
    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
                <configuration>
                    <mainClass>org.demo.hookjava.HookJavaApplication</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
Configure your Webhook URL in the NavTalk console: Log in to the NavTalk Console, go to project settings, and configure the following Webhook URLs:
  • Real-time Event Webhook: https://your-domain.com/api/webhook/message
  • Session Record Webhook: https://your-domain.com/api/webhook/session
Deploy your application (Spring Boot / Flask / ASP.NET Core), ensure your server is publicly accessible, create a test session in NavTalk, and check your server logs to confirm Webhook events have been received.

Data Format

MessageData Format - Real-time event data format:
{
  "event": "conversation.output",
  "sessionId": "session_123456",
  "role": "ai",
  "timestamp": "2024-01-15T10:30:00Z",
  "message": "Hello, how can I help you?"
}
Field Descriptions:
FieldTypeDescription
eventstringEvent type: session.created, conversation.output, session.closed
sessionIdstringUnique session identifier
rolestringMessage role: ai, user, system
timestampstringEvent timestamp (ISO 8601 format)
messagestringMessage content (only present in conversation.output events)
SessionData Format - Complete session record data format:
{
  "sessionId": "session_123456",
  "startTime": "2024-01-15T10:00:00Z",
  "endTime": "2024-01-15T10:30:00Z",
  "messages": [
    {
      "event": "conversation.output",
      "sessionId": "session_123456",
      "role": "user",
      "timestamp": "2024-01-15T10:00:05Z",
      "message": "Hello"
    },
    {
      "event": "conversation.output",
      "sessionId": "session_123456",
      "role": "ai",
      "timestamp": "2024-01-15T10:00:10Z",
      "message": "Hello, how can I help you?"
    }
  ]
}