Skip to main content

Overview

A Chargebee connection in Tirdad stores encrypted credentials that allow the system to interact with your Chargebee account for:
  • Creating item families, items, and item prices in Chargebee
  • Synchronizing customers to Chargebee
  • Syncing invoices to Chargebee for payment collection
  • Receiving webhook notifications from Chargebee

Prerequisites

Before setting up your Chargebee connection, ensure you have:
  1. Active Chargebee Account - Sign up at chargebee.com
  2. API Key - Available in your Chargebee Dashboard
  3. Webhook Endpoint - Configured in Chargebee Dashboard
  4. Tirdad Environment - Valid tenant and environment IDs

Step 1: Gather Chargebee Credentials

Required Credentials

Finding Your Credentials

  1. Site Name:
    • Go to Chargebee Dashboard → Settings → API & Webhooks
    • Your site name is displayed at the top (e.g., acme-test)
  2. API Key:
    • Go to Chargebee Dashboard → Settings → API & Webhooks → API Keys
    • Copy your API key (starts with your site name)
    • Use test API keys for development
  3. Webhook Credentials (Optional):
    • Go to Chargebee Dashboard → Settings → API & Webhooks → Webhooks
    • Configure Basic Authentication for webhook security
    • Copy the username and password

Step 2: Configure Webhook Endpoint in Chargebee

Webhook URL Format

Required Webhook Events

Configure these events in your Chargebee webhook endpoint:

Setting Up the Webhook

  1. Go to Chargebee Dashboard → Settings → API & Webhooks → Webhooks
  2. Click + Add New Webhook
  3. Enter your webhook URL
  4. Select the required events listed above
  5. Configure Basic Authentication (optional but recommended)
  6. Click Save

Step 3: Create Chargebee Connection

Using Tirdad Dashboard

You can create a Chargebee connection directly from the Tirdad dashboard.
Connect to Chargebee

API Request

Endpoint: POST /api/v1/connections Headers:
Request Body:

Response

Editing an Existing Connection

You can edit an existing Chargebee connection to update its name and sync configuration. To find it, open Integrations → Chargebee and click the pencil icon next to the connection under Connected Accounts.
Edit Chargebee Connection
Editable Fields:
  • Connection Name: Update the friendly name for the connection
  • Sync Configuration: Enable or disable invoice sync
  • Webhook Configuration: Shows the webhook URL and the events to subscribe to
The edit drawer does not show the API key, site or webhook username and password. To change them, delete the connection and create a new one.

Security Best Practices

Credential Management

  1. Environment Separation: Use different API keys for test/production
  2. Key Rotation: Regularly rotate your Chargebee API keys
  3. Access Control: Limit API key permissions in Chargebee
  4. Encryption: All credentials are encrypted at rest in Tirdad

Webhook Security

  1. HTTPS Only: Always use HTTPS for webhook endpoints
  2. Basic Authentication: Use Basic Auth for webhook verification (recommended)
  3. Secret Management: Keep webhook credentials secure and rotate regularly
  4. Rate Limiting: Implement rate limiting on webhook endpoints

Troubleshooting

Common Issues

Debug Steps

  1. Check Chargebee Dashboard: Verify API key and site name
  2. Test API Key: Use Chargebee API to test key validity
  3. Monitor Webhooks: Check webhook delivery logs in Chargebee
  4. Review Logs: Check Tirdad application logs for errors

Next Steps

After setting up your Chargebee connection:
  1. Create Item Family: Create an item family in Chargebee (required for plan sync)
  2. Sync Plans: Sync your Tirdad plans to Chargebee
  3. Test Invoice Sync: Create a test invoice and sync to Chargebee
  4. Monitor Webhooks: Ensure webhook events are being received
  5. Go Live: Switch to production credentials when ready