Route Import & Export: Move Configs Between Environments

The Challenge of Multi-Environment Webhook Management

Setting up webhook routes is straightforward. Setting them up again in a new environment? That's where things get tedious. Recreating routes manually across staging, production, and disaster recovery environments is time-consuming and error-prone.

Most teams run multiple environments: development, staging, production, maybe a disaster recovery site. Each needs the same webhook routing logic, but traditionally you had two options:

1. Manual recreation: Click through the UI for each environment, hoping you don't miss a filter condition or notification setting
2. Infrastructure as code: Build custom scripts to create routes via API, maintaining yet another configuration layer

Both approaches have friction. Manual work doesn't scale. Custom scripts need maintenance. And neither makes it easy to share a working route configuration with a teammate.

The Solution: Portable JSON Configuration

With Route Import & Export, your entire routing setup becomes a portable JSON file:

{
  "version": "1.0",
  "exportedAt": "2026-01-30T12:00:00Z",
  "organizationSlug": "acme-corp",
  "routes": [
    {
      "name": "Stripe to Slack",
      "sourceSlug": "stripe-webhooks",
      "destinationSlug": "slack-notifications",
      "filterSlug": "payment-events",
      "priority": 10,
      "isActive": true,
      "notifyOnFailure": true,
      "failoverDestinationSlugs": ["backup-webhook"]
    }
  ]
}

Notice the key design decision: everything uses slugs, not IDs. This means your export file works across any organization that has matching source and destination slugs. Set up your staging and production environments with the same slugs, and configurations transfer seamlessly.

How It Works

Exporting Routes

From the Routes page, click the Export dropdown:

• Export All: Downloads every route in your organization
• Export Selected: Select specific routes with checkboxes, then export just those

The JSON file includes everything: filters, transforms, schemas, notification settings, failover destinations, and circuit breaker configuration.

Importing Routes

Click Import to open the import wizard:

1. Upload: Drag and drop your JSON file or click to browse
2. Preview: See exactly what will be imported, with validation warnings for missing dependencies
3. Choose conflict handling: Decide what happens when a route name already exists
4. Import: One click to create all routes

Smart Conflict Handling

When importing routes that share names with existing ones, you choose the strategy:

| Strategy | Behavior | |----------|----------| | Skip | Keep the existing route, don't import the duplicate | | Rename | Import with a suffix: "My Route" becomes "My Route (1)" | | Overwrite | Replace the existing route with the imported configuration |

The preview step shows exactly what will happen before you commit.

Validation Before Import

Before any routes are created, Hookbase validates:

• All referenced sources exist in the target organization
• All referenced destinations exist
• All referenced filters, transforms, and schemas exist
• Your plan limits aren't exceeded

If something's missing, you'll see a clear error: "Source 'stripe-webhooks' not found. Create it first."

Use Cases

Staging to Production Deployments

Test your route configuration in staging. When it's working, export and import to production. No manual recreation, no missed settings.

# Export from staging
curl "https://api.hookbase.app/api/organizations/acme-staging/routes/export" \
  -H "Authorization: Bearer $STAGING_TOKEN" \
  -o routes.json

# Import to production
curl -X POST "https://api.hookbase.app/api/organizations/acme-prod/routes/import" \
  -H "Authorization: Bearer $PROD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "routes": '"$(cat routes.json | jq '.routes')"',
    "conflictStrategy": "skip"
  }'

Backup and Disaster Recovery

Export your routes periodically and store the JSON in version control or your backup system. If you ever need to rebuild, import gets you back to operational in seconds.

Team Collaboration

Built a complex route with multiple filters and failover destinations? Export it and share with teammates. They can import into their own organization or a shared development environment.

Onboarding New Organizations

When setting up a new customer organization with similar routing needs, start from an exported template rather than building from scratch.

API Reference

Export Routes

# Export all routes
GET /api/organizations/{orgId}/routes/export

# Export specific routes
GET /api/organizations/{orgId}/routes/export?ids=route1,route2,route3

Import Routes

POST /api/organizations/{orgId}/routes/import
Content-Type: application/json

{
  "routes": [...],
  "conflictStrategy": "skip" | "rename" | "overwrite",
  "validateOnly": true  // Optional: dry-run to check for errors
}

The validateOnly flag lets you preview what would happen without making changes, useful for CI/CD pipelines that need to verify imports will succeed.

What Gets Exported

Every route setting is included:

• Basic configuration: Name, source, destination, priority, active state
• Filtering: Referenced filter or inline filter conditions with logic (AND/OR)
• Transformation: Referenced transform
• Validation: Referenced schema
• Notifications: Failure, success, and recovery notification settings
• Failover: Backup destinations and failover trigger thresholds
• Circuit breaker: Cooldown, failure threshold, and probe settings

Getting Started

1. Go to Routes in your Hookbase dashboard
2. Click Export to download your current configuration
3. Set up your target environment with matching source and destination slugs
4. Click Import and upload the JSON file
5. Review and confirm: Your routes are ready

Route Import & Export is available now on all plans. Whether you're managing a single production environment or orchestrating webhooks across a dozen regions, portable configuration makes it simpler.

---

Questions about route management or multi-environment setups? Join our Discord community or reach out to [email protected].