BoldDesk may not provide a native integration for every third-party application. When a native integration is unavailable, you can connect the external system using REST APIs, webhooks, Custom Apps, or middleware.

This article explains how to choose an integration method, design one-way or two-way data flows, display external data in BoldDesk, secure the integration, and troubleshoot common integration failures.

Choose an Integration Architecture

Select the integration method based on the required data flow and the responsibilities that the integration must handle.

BoldDesk REST APIs support resources such as tickets, contacts, Contact Groups, groups, and fields. The available operations depend on the selected resource and endpoint.

A simple one-way integration may use only one component. For example:

• Use a webhook to send BoldDesk ticket events to an external reporting system.
• Use the REST API to create BoldDesk tickets from an external application.
• Use a Custom App to display CRM or subscription information inside a BoldDesk ticket.

For two-way synchronization, use middleware to manage:

• Field and status mapping
• BoldDesk and external record ID correlation
• Payload validation and transformation
• Controlled retries
• API rate limits
• Duplicate-event prevention
• Synchronization-loop prevention
• Conflict resolution
• Audit logging
• Secure credential storage

Prerequisites

Before building the integration, ensure that:

• A licensed BoldDesk agent account can generate an API key.
• The agent account has permission to access the required resources and brands.
• An administrator can manage webhooks and Custom Apps.
• The external application provides an API or another supported integration mechanism.
• A publicly accessible HTTPS endpoint is available for webhooks and Custom Apps.
• The endpoint can receive and process JSON requests.
• Secure storage is available for API keys, passwords, and signing secrets.
• The required field mappings and synchronization rules are documented.
• A test environment or non-production dataset is available.

Send Data from BoldDesk to an External System

Use a webhook when an external application must be notified after a supported event occurs in BoldDesk.

Examples include:

• A ticket is created or updated.
• A ticket status changes.
• A contact is created or updated.
• A Contact Group is created, updated, or deleted.
• Another supported module event occurs.

A typical webhook workflow is:

1. A supported event occurs in BoldDesk.
2. BoldDesk sends the configured payload to the webhook endpoint.
3. The endpoint authenticates the request and validates its signature.
4. Middleware transforms the payload when required.
5. Middleware calls the external application’s API.
6. Middleware records the result for auditing and retry handling.

BoldDesk webhooks support configurable modules, events, HTTP methods, authentication, signing, conditions, and payloads. Failed webhook requests are recorded in Webhook Failure Logs.

For complete webhook configuration instructions, learn more on How to Create and Manage Webhooks in BoldDesk Tickets.

Receive Data from an External System

Use the BoldDesk REST API when a third-party application must create or update data in BoldDesk.

A typical API-driven workflow is:

1. A record changes in the external application.
2. The external application sends an event to middleware.
3. Middleware validates and transforms the data.
4. Middleware locates the corresponding BoldDesk record.
5. Middleware calls the applicable BoldDesk REST API endpoint.
6. Middleware stores the returned record ID and operation result.

REST API operations can include the following methods, depending on the resource and endpoint:

The BoldDesk Developer API reference defines the URL, HTTP method, headers, request properties, and response schema for each endpoint.

Authenticate REST API Requests

BoldDesk REST API requests use API key authentication.

To authenticate a request:

1. Generate an API key from the agent’s profile.
2. Store the API key securely.
3. Pass the key in the x-api-key request header.
4. Use only the permissions required by the integration.
5. Revoke or rotate the key when it is exposed or no longer required.

Example headers:

x-api-key: YOUR_API_KEY
Content-Type: application/json

Use /api/v1/ in the endpoint URL. Do not use /api/v1.0/.

For the current endpoint catalog and request schemas, explore more on BoldDesk Developer API Reference.

Create a Ticket from an External Application

Use the Tickets API when an event in an external application must create a ticket in BoldDesk.

For example:

1. An order is cancelled in an external order-management application.
2. The application sends the event to middleware.
3. Middleware maps the customer and order information.
4. Middleware calls the applicable BoldDesk ticket-creation endpoint.
5. The returned Ticket ID is stored with the external record.
6. Future events use the stored Ticket ID to update the same ticket.

Before creating the request, use the Developer API reference to confirm:

• Ticket-creation endpoint
• Required fields
• Brand and form requirements
• Supported priority and status values
• Custom-field API names
• Validation limits
• Response schema

Display External Data Using a Custom App

Use a Custom App when agents need to view external information without leaving BoldDesk.

Custom Apps can display external data on:

• Ticket details pages
• Contact pages
• Contact Group pages

Examples include:

• Customer subscription status
• Account balance
• Recent orders
• Contract information
• Shipping details
• External incident records
• CRM account information

When an agent opens a Custom App:

1. BoldDesk sends a POST request to the configured HTTPS endpoint.
2. The request contains the selected payload fields.
3. If no payload is selected, BoldDesk sends an empty object, {}.
4. The endpoint retrieves or calculates the required external information.
5. The endpoint returns JSON containing an HTML message and a statusCode.
6. BoldDesk displays the supported HTML in the app panel.

Configure a Custom App

To create a Custom App:

1. Go to Admin → My Apps.

2. Select Add Custom App.

3. Enter a unique app name.

4. Enter an optional description.

5. Upload an optional logo.

6. Enter the public POST HTTPS endpoint.

7. Configure authentication when required.

8. Configure request signing when required.

9. Select the payload fields to send.

10. Configure app visibility by role.

11. Select Add.

    
    
    

Configure the following settings:

For complete configuration instructions, explore further information on How to Add and Manage Custom Apps in BoldDesk.

Build the Custom App Endpoint

The Custom App endpoint must:

1. Accept an HTTPS POST request.
2. Validate the configured authentication.
3. Validate the x-signature header when request signing is enabled.
4. Read the incoming payload.
5. Retrieve the required external information.
6. Generate supported HTML.
7. Return a JSON response within 10 seconds.

A successful response uses the following structure:

{
  "message": "<h6>Customer Information</h6><p><strong>Name:</strong> ABC Hospital</p><p><strong>Plan:</strong> Premium Support</p><p><strong>Status:</strong> Active</p>",
  "statusCode": "200"
}

An error response can use:

{
  "message": "Unauthorized",
  "statusCode": "401"
}

BoldDesk cancels the Custom App request if the endpoint does not respond within 10 seconds.

Follow the Custom App HTML Requirements

Custom Apps support a restricted set of HTML tags, attributes, and predefined CSS classes.

The following limitations apply:

• Inline CSS is not supported.
• JavaScript is not supported.
• Only supported HTML tags and attributes are rendered.
• Unsupported HTML can be removed.
• Links are the supported interactive element.

Use the Style Guide for Custom Apps in BoldDesk to confirm:

• Supported HTML tags
• Supported attributes
• Available CSS classes
• Link requirements
• Accordion markup
• Text and background styles
• Unsupported elements

Build a Two-Way Synchronization

Use middleware when the same data must be synchronized between BoldDesk and the external application.

The middleware should manage:

Prevent Synchronization Loops

Without loop prevention, the same update can move repeatedly between both systems.

For example:

1. A contact changes in the external CRM.
2. Middleware updates the BoldDesk contact.
3. A BoldDesk webhook
4. Middleware sends the change back to the CRM.
5. The CRM generates another event.

Prevent this behavior by storing:

• Source system
• External event ID
• Correlation ID
• Last synchronized value
• Last synchronization time

Ignore an event when the integration has already processed the same change.

Secure Webhooks and Custom Apps

Webhook and Custom App endpoints must use HTTPS. Local addresses such as localhost are not supported. Authentication and request signing are strongly recommended.

BoldDesk supports the following endpoint-security options:

• Password-based Basic Authentication
• API key-based Basic Authentication
• HMAC-SHA256 request signing
• Base64-encoded signatures in the x-signature header

Apply the following security practices:

• Keep API keys and signing secrets outside application source code.
• Rotate exposed credentials immediately.
• Verify request signatures before processing payloads.
• Reject requests with invalid authentication.
• Validate payload types, lengths, and permitted values.
• Log request identifiers without logging secrets.
• Return only the data required by the Custom App.
• Restrict Custom App visibility using role permissions.
• Use separate credentials for development and production.

For complete webhook security requirements, learn How to Secure Webhooks in BoldDesk.

Troubleshoot Integration Errors

The BoldDesk Developer API can return status codes such as:

Use Cases

1. Create a Ticket from an External Event
   An order-management system reports that an order was cancelled. Middleware receives the event and creates a BoldDesk ticket containing the customer and order details.

2. Display Subscription Data in a Ticket
   An agent opens a Custom App from a ticket. The endpoint identifies the customer, queries the subscription platform, and returns the current plan and account status as supported HTML.

3. Synchronize Contacts in Both Directions
   An external CRM reports a customer phone-number change. Middleware updates the matching BoldDesk contact. A later BoldDesk contact update triggers a webhook that updates the CRM.

4. Synchronize Contact Groups with External Organizations
   A Contact Group is created or updated in BoldDesk. A webhook notifies middleware, which creates or updates the corresponding organization record in the external system.

Frequently Asked Questions

1. Which Integration Method Should I Use?
   Use:

   • REST APIs to read or modify BoldDesk data.
   • Webhooks to notify an external endpoint about supported events.
   • Custom Apps to display external information inside BoldDesk.
   • Middleware when synchronization, mapping, retries, or conflict handling is required.

2. Can a Custom App Use HTTP or Localhost?
   No. The endpoint must use HTTPS and must be publicly accessible. Local environments such as localhost are not supported.

3. How Long Does BoldDesk Wait for a Custom App Response?
   BoldDesk waits up to 10 seconds. The request is cancelled if the endpoint does not respond within that period.

4. Can One Webhook Send Events to Multiple Destinations?
   Create a separate webhook for each destination. Apply conditions when each endpoint should receive only specific brands or event patterns.

5. Does BoldDesk Provide a Native Integration for Every Application?
   No. When a native integration is unavailable, use REST APIs, webhooks, Custom Apps, or middleware according to the required workflow.

Related Articles

1. BoldDesk REST API Overview for Developers
2. How to Add and Manage Custom Apps in BoldDesk
3. Style Guide for Custom Apps in BoldDesk
4. How to Create and Manage Webhooks in BoldDesk Tickets
5. How to Secure Webhooks in BoldDesk
6. BoldDesk Developer API Reference