Using Bring Your Own Data (BYOD) plugin

This guide is public and intended for technical admins configuring BYOD in initdesk.

What BYOD does

BYOD lets initdesk call your external endpoint, then render a plugin panel in tickets using the data returned by your system.

Use BYOD when you want agents to see context like:

• CRM plan and lifecycle status

• Last invoice/payment details

• Internal account health fields

• Any custom data keyed by customer email

​

Before you start

Make sure you have:

• Access to your organization plugin settings in initdesk

• A reachable HTTPS endpoint you control

• A way to identify customers by email in your external system

Open the BYOD settings

1. In initdesk, go to Settings.

2. Open Plugins.

3. Click Bring Your Own Data (BYOD).

Configure BYOD (field-by-field)

Required fields

• Endpoint URL

  • Must be a valid HTTPS URL.

  • This is the endpoint initdesk uses to fetch data for rendering.

• Template

  • Required.

  • Used by the backend to render final panel output -- uses Liquid syntax.

Optional fields

• Headers

  • Optional key/value headers added to every request.

  • Useful for API versioning and custom authorization headers.

• Request timeout

  • Optional.

  • Allowed range: 1 to 10.

  • Use lower values to protect ticket-view performance.

• X-Initdesk-Key

  • Optional secret to validate the request.

  • Forwarded as X-Initdesk-Key to your endpoint.

• Panel title

  • Optional panel heading displayed in the sidebar.

• Panel description

  • Optional helper text shown below the heading.

​

Preview before saving

Use Live preview in the BYOD screen to validate output without persisting configuration changes.

The webhook makes a POST request to your endpoint with the following payload:

{
  "email": "customer@email.com",
  "ticket_id": 123,
  "subject": "Ticket subject"
}

​

Liquid template example

In BYOD templates, your external API response is available under data.

If your API returns:

{
  "customer": {
    "name": "Ana Rivera",
    "plan": "Pro",
    "status": "active",
    "renewal_date": "2026-09-12"
  }
}

You can render it with:

<dl>
  <dt>Customer</dt>
  <dd>{{ data.customer.name }}</dd>
  <dt>Plan</dt>
  <dd>{{ data.customer.plan }}</dd>
  <dt>Status</dt>
  <dd>{{ data.customer.status }}</dd>
  <dt>Renewal date</dt>
  <dd>{{ data.customer.renewal_date }}</dd>
</dl>
</div>

Troubleshooting

• Access denied

  • You do not have permission to configure this BYOD integration.

  • Ask an organization admin to update your role.

• Preview fails

  • Check endpoint reachability and response latency.

  • See "JSON Response" tab for debug information -- request and response data is displayed to help find the issue.

• Rendered output is not as expected

  • Verify Liquid variable paths match your response shape under data.

  • Test with a known customer payload and simplify template logic first.

​

Security and reliability best practices

• Keep secrets out of templates and logs.

• Return only the fields needed for agent context.

• Sanitize and validate any HTML generated in your integration pipeline.

• Keep endpoint response times low to avoid degraded ticket-view experience.

​

Recommended rollout flow

1. Start with one use case and a minimal template.

2. Verify preview output for multiple customer records.

3. Save configuration and validate in live tickets.

4. Expand template and data gradually after baseline stability.

​

​