DigiReply Tickets Webhook Documentation

Ticket Creation Methods

DigiReply offers multiple ways to create tickets, each designed for different use cases. All ticket creation methods trigger webhooks, allowing you to receive real-time updates in your systems.

Overview

DigiReply's ticket webhook system enables real-time integration with your ticketing system by sending notifications about ticket-related events. This allows you to track and respond to ticket activities, automate workflows, and maintain synchronized ticket data across your systems.

Benefits of Using Ticket Webhooks

• Real-Time Updates: Receive instant notifications when tickets are created, updated, or responded to.
• System Integration: Integrate ticket data with your CRM, help desk, or custom applications.
• Automation: Trigger automated workflows based on ticket events.
• Data Tracking: Maintain comprehensive logs of all ticket activities.

Supported Events

The ticket webhook system supports four main event types, each providing specific information about ticket activities:

{
    "event": "ticket.created",
    "secret_key": "your_webhook_secret",
    "data": {
        "ticket_id": "123",
        "ticket_number": "TIC-20240321-1234",
        "subject": "Technical Issue",
        "description": "Need help with integration",
        "status": "open",
        "priority": "medium",
        "created_by": "john_doe",
        "created_by_email": "john@example.com",
        "project": "My Project"
    }
}

{
    "event": "ticket.updated",
    "secret_key": "your_webhook_secret",
    "data": {
        "ticket_id": "123",
        "status": "in_progress",
        "priority": "high",
        "updated_by": "jane_smith",
        "changes": {
            "status": ["open", "in_progress"],
            "priority": ["medium", "high"]
        },
        "project": "My Project"
    }
}

{
    "event": "ticket.deleted",
    "secret_key": "your_webhook_secret",
    "data": {
        "ticket_id": "123",
        "deleted_by": "admin_user",
        "project": "My Project"
    }
}

{
    "event": "ticket.response.added",
    "secret_key": "your_webhook_secret",
    "data": {
        "ticket_id": "123",
        "response_by": "support_agent",
        "response_text": "Here's the solution to your issue...",
        "is_private": false,
        "project": "My Project"
    }
}

Setup Instructions

Step 1: Configure Your Webhook Endpoint

1. Create the Webhook File:
   • Create a new file named ticket-webhook.php in your web server directory.
   • Ensure PHP has write permissions for the directory where logs will be stored.
   • Configure your database connection in config/database.php.
2. Set Up Error Logging:
   • Enable error logging to track any issues with webhook processing.
   • Ensure the log directory is writable by your web server.

Step 2: Register Your Webhook

1. Access Webhook Settings:
   • Log in to your DigiReply dashboard.
   • Navigate to Settings → Webhooks.
2. Add New Webhook:
   • Click "Add New Webhook".
   • Enter your webhook URL (e.g., https://your-domain.com/ticket-webhook.php).
   • Select the ticket events you want to receive (ticket.created, ticket.updated, etc.).
   • Save the generated secret key - you'll need this in your webhook script.

Implementation Example

Complete Webhook Handler Implementation

Below is a production-ready implementation of a ticket webhook handler that processes all ticket events and logs them to a file:

<?php
require_once 'config/database.php';

// Set response header to JSON
header('Content-Type: application/json');

// Enable error logging
ini_set('log_errors', 1);
ini_set('error_log', 'ticket_webhook_error.log');

// Your webhook secret key from the webhook settings panel
$webhook_secret = 'PASTE_YOUR_SECRET_KEY_HERE'; // User should paste their secret key here

// Read the JSON payload
$input = file_get_contents('php://input');
error_log("Received webhook data: " . $input); // Debug log
$payload = json_decode($input, true);

if (!$payload) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid JSON payload']);
    exit;
}

// Debug what we received
error_log("Decoded payload: " . print_r($payload, true));

// Simple secret key verification
if (!isset($payload['secret_key']) || $payload['secret_key'] !== $webhook_secret) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid secret key']);
    exit;
}

// Get the event type
$event = $payload['event'] ?? 'unknown';

// Write to tickets.txt file
$log_entry = [
    'timestamp' => date('Y-m-d H:i:s'),
    'event' => $event,
    'data' => []
];

switch ($event) {
    case 'ticket.created':
        $log_entry['data'] = [
            'ticket_id' => $payload['data']['ticket_id'] ?? null,
            'ticket_number' => $payload['data']['ticket_number'] ?? null,
            'project_name' => $payload['data']['project'] ?? null,
            'priority' => $payload['data']['priority'] ?? null,
            'status' => $payload['data']['status'] ?? null,
            'created_by' => $payload['data']['created_by'] ?? null,
            'created_by_email' => $payload['data']['created_by_email'] ?? null,
            'subject' => $payload['data']['subject'] ?? null,
            'description' => $payload['data']['description'] ?? null
        ];
        break;
        
    case 'ticket.updated':
        $log_entry['data'] = [
            'ticket_id' => $payload['data']['ticket_id'] ?? null,
            'status' => $payload['data']['status'] ?? null,
            'priority' => $payload['data']['priority'] ?? null,
            'updated_by' => $payload['data']['updated_by'] ?? null,
            'changes' => $payload['data']['changes'] ?? [],
            'project_name' => $payload['data']['project'] ?? null
        ];
        break;
        
    case 'ticket.deleted':
        $log_entry['data'] = [
            'ticket_id' => $payload['data']['ticket_id'] ?? null,
            'deleted_by' => $payload['data']['deleted_by'] ?? null,
            'project_name' => $payload['data']['project'] ?? null
        ];
        break;
        
    case 'ticket.response.added':
        $log_entry['data'] = [
            'ticket_id' => $payload['data']['ticket_id'] ?? null,
            'response_by' => $payload['data']['response_by'] ?? null,
            'response_text' => $payload['data']['response_text'] ?? null,
            'is_private' => $payload['data']['is_private'] ?? false,
            'project_name' => $payload['data']['project'] ?? null
        ];
        break;
}

$log_line = json_encode($log_entry) . PHP_EOL;
error_log("Writing to tickets.txt: " . $log_line); // Debug log
file_put_contents('tickets.txt', $log_line, FILE_APPEND | LOCK_EX);

// Send success response
echo json_encode([
    'success' => true,
    'message' => 'Event logged successfully'
]);

Testing

Testing with cURL

You can test your webhook implementation using cURL commands. Here are examples for each event type:

Test Ticket Creation

curl -X POST https://your-domain.com/ticket-webhook.php \
-H "Content-Type: application/json" \
-d '{
    "event": "ticket.created",
    "secret_key": "your_webhook_secret",
    "data": {
        "ticket_id": "123",
        "ticket_number": "TIC-20240321-1234",
        "subject": "Test Ticket",
        "description": "Testing webhook integration",
        "status": "open",
        "priority": "medium",
        "created_by": "test_user",
        "project": "Test Project"
    }
}'
                        

Expected Response

{
    "success": true,
    "message": "Event logged successfully"
}
                        

Gathering both web generated tickets and bot generated tickets into one place

Centralizing ticket logging from different sources (web forms and chatbots) provides several key benefits:

• Unified Tracking: Maintain a single source of truth for all tickets regardless of origin
• Consistent Format: Standardize ticket data structure for easier processing and analysis
• Simplified Integration: One standardized format makes it easier to integrate with other systems
• Better Analytics: Compare and analyze tickets from different sources in one place
• Streamlined Debugging: Easier to track and debug issues when all logs follow the same format

Chatbot Ticket Webhook Implementation

Below is a complete implementation example for handling chatbot-generated tickets while maintaining consistency with web-generated tickets:

<?php
require_once 'config/database.php';  // Include database connection

// webhook.php

// Secret token for basic authentication
define('WEBHOOK_SECRET', 'PASTE_YOUR_SECRET_KEY_HERE');

// Set response header to JSON
header('Content-Type: application/json');

// Enable error logging
ini_set('log_errors', 1);
ini_set('error_log', 'webhook_error.log');

// Verify the Authorization header
$headers = getallheaders();
$auth_header = isset($headers['Authorization']) ? $headers['Authorization'] : '';
if ($auth_header !== 'Bearer ' . WEBHOOK_SECRET) {
    error_log("Unauthorized access attempt: auth_header='$auth_header'");
    http_response_code(401);
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}

// Read the JSON payload
$input = file_get_contents('php://input');
$payload = json_decode($input, true);
if (!$payload) {
    error_log("Invalid JSON payload: input='$input'");
    http_response_code(400);
    echo json_encode(['error' => 'Invalid JSON payload']);
    exit;
}

// Determine event_type
$event_type = isset($payload['event_type']) ? $payload['event_type'] : '';
if ($event_type !== 'on_ticket_created') {
    error_log("Invalid event type: event_type='$event_type', payload=" . json_encode($payload));
    http_response_code(400);
    echo json_encode(['error' => 'Invalid event type']);
    exit;
}

// Initialize response
$response = ['status' => 'success'];

// Handle on_ticket_created event
if ($event_type === 'on_ticket_created') {
    // Validate required fields
    if (!isset($payload['ticket_number']) || !isset($payload['bot_id']) || !isset($payload['visitor_id'])) {
        error_log("Missing required fields for on_ticket_created: payload=" . json_encode($payload));
        http_response_code(400);
        echo json_encode(['error' => 'Missing required fields']);
        exit;
    }

    try {
        // Get project name from bot_id
        $stmt = $pdo->prepare("
            SELECT p.name as project_name 
            FROM bots b 
            JOIN projects p ON b.project_id = p.id 
            WHERE b.id = ?
        ");
        $stmt->execute([$payload['bot_id']]);
        $project = $stmt->fetch(PDO::FETCH_ASSOC);

        // Create standardized log entry
        $log_entry = [
            'timestamp' => date('Y-m-d H:i:s'),
            'event' => 'ticket.created',
            'source' => 'chatbot',
            'data' => [
                'ticket_number' => $payload['ticket_number'],
                'project_name' => $project['project_name'] ?? 'Unknown Project',
                'priority' => 'medium',  // Default priority for chatbot tickets
                'status' => 'open',
                'created_by' => $payload['ticket_data']['name'] ?? 'Unknown',
                'created_by_email' => $payload['ticket_data']['email'] ?? 'Unknown',
                'subject' => isset($payload['ticket_data']['name']) ? 
                            "Support Ticket from " . $payload['ticket_data']['name'] : 
                            "Support Ticket",
                'description' => $payload['ticket_data']['description'] ?? '',
                'bot_id' => $payload['bot_id'],
                'visitor_id' => $payload['visitor_id']
            ]
        ];

        $log_file = 'tickets.txt';
        error_log("Writing standardized format to tickets.txt: " . json_encode($log_entry));
        
        if (!is_writable($log_file) && !touch($log_file)) {
            error_log("Cannot write to tickets.txt: file is not writable");
        }
        
        if (!file_put_contents(
            $log_file,
            json_encode($log_entry) . PHP_EOL,
            FILE_APPEND | LOCK_EX
        )) {
            error_log("Failed to write to tickets.txt");
        }
    } catch (Exception $e) {
        error_log("Error processing ticket webhook: " . $e->getMessage());
        http_response_code(500);
        echo json_encode(['error' => 'Internal server error']);
        exit;
    }

    // Override response for ticket creation
    $response['action'] = 'override_response';
    $response['response'] = "Ticket {$payload['ticket_number']} has been created successfully.";
}

// Respond with success
http_response_code(200);
echo json_encode($response);
?>

Note: This implementation ensures that tickets created through the chatbot are logged in the same format as those created through web forms, making it easier to:

• Track tickets across all channels
• Generate unified reports
• Maintain consistent ticket handling workflows
• Integrate with external systems

Verifying Webhook Operation

1. Check tickets.txt for new log entries
2. Review ticket_webhook_error.log for any errors
3. Verify the webhook URL is accessible from DigiReply servers
4. Confirm the secret key matches in both the webhook settings and your script

Best Practices

Security

• HTTPS Required: Always use HTTPS for your webhook endpoint
• Validate Secret Key: Always verify the webhook secret key
• Sanitize Input: Sanitize and validate all incoming data
• Secure Storage: Store sensitive data (like secret keys) securely

Performance

• Quick Response: Process webhooks quickly to avoid timeouts
• Async Processing: Use queues for time-consuming operations
• Error Handling: Implement comprehensive error handling
• Logging: Maintain detailed logs for debugging

Troubleshooting

Common Issues

• Webhook Not Receiving Events
  • Verify the webhook URL is correct and accessible
  • Check the secret key matches
  • Ensure selected events are enabled in webhook settings
• File Permission Issues
  • Check write permissions for log files
  • Verify PHP has permission to write to the directory
• Invalid JSON Errors
  • Validate JSON payload format
  • Check for proper encoding of special characters

Debug Tips

• Enable debug logging in your webhook script
• Monitor the error log file for detailed error messages
• Use test endpoints like RequestBin for payload inspection

Support

If you need assistance with ticket webhooks:

• Email: support@digireply.com
• Documentation: Help Center