This month, on top of all the of the amazing updates and releases from Spring Spotlight 2026, we also have updates regarding the availability of our legacy CRM card migration tool, new features for the Custom Channels API, and more. Make sure to read on below for more details.

Legacy CRM Card Migration Tool Now Available

Starting April 21st, 2026, HubSpot introduced the Legacy CRM Card View Swapping Tool, which enables developers to migrate Legacy CRM Cards to UI Extension App Cards without disrupting existing customer CRM views.

Legacy CRM Cards are scheduled for deprecation on October 31st, 2026. Without migration, legacy CRM cards will eventually disappear from customer views that use them. The View Swapping Tool allows developers to proactively replace legacy cards with HubSpot’s newer App Cards while preserving existing view placements and minimizing customer impact.

The Legacy CRM Card View Swapping Tool is a developer-initiated migration workflow that:

• Replaces a legacy CRM card with a UI extension app card.
• Automatically updates existing customer CRM views.
• Requires no action from customers.
• Runs asynchronously across all app installs.

The migration with the swapping tool hides the legacy card and displays the replacement App Card in the same view locations.

What's changing?

New Capabilities

• A new migrate views API endpoint to replace legacy CRM cards with app cards in existing customer views.
• Support for the following view locations:
• crm.record.sidebar
• helpdesk.sidebar (explicitly required for ticket cards).
• Example App Cards, Postman Collection, and Figma design resources to accelerate migration.

Deprecation Reminder

Legacy CRM Cards will be fully deprecated on October 31st, 2026, and can no longer be created via the HubSpot UI.

Who Needs to Take Action

Developers should migrate if:

• Your app currently uses legacy CRM cards.
• Your app is installed in customer accounts where those cards appear in CRM views.
• You want to prevent customer-facing regressions when legacy cards are deprecated.

What does this mean for developers?

To begin migrating a legacy CRM card to an app card, follow the steps below or refer to this video demo.

Step 1: Prepare Your App
Upgrade to the latest HubSpot CLI version and connect to your HubSpot account:

Step 2: Migrate Your App
Ensure your Public (legacy) app is on the Projects Framework (Developer Platform version 2026.03+). If your app is not on the Project Framework, run: hs app migrate.

This migrates your app and existing legacy CRM cards without impacting customers.

Note: If you need additional references to migrate your app to the new framework, please refer to these guides:

• Migrate an existing public app to the projects framework

If your app is already project-based, run: hs project migrate.

Step 3: Create a Replacement App Card
Build a new UI extension app card to replace the legacy CRM card. There are two approaches depending on your goal:

• Option A: Redesign from scratch using the UI extension React components to take full advantage of the new framework’s capabilities. Figma resources are available for design support.
• Option B: Use the Legacy Card Converter for a quick migration that replicates your existing card’s behavior. Note that some differences apply, such as action requests using JSON instead of URL-encoded bodies and static card titles. See the README.md for more information.
  Note: Develop and test App Cards in a separate testing app before deploying to production, as once view swapping has been initiated, it cannot be reversed.

Important migration notes

Ticket Support Considerations
If your legacy CRM card supports tickets, it’s important to note the following:

• Legacy cards automatically appear in the helpdesk.sidebar location.
• App cards do not.
• You must create two App Cards for each location, and each requires a unique title and extension card ID:
• crm.record.sidebar
• helpdesk.sidebar

Release the App Card
For migrated Marketplace apps:

• New app cards are hidden by default behind the hs-release-app-cards feature flag, which HubSpot auto-creates during migration and gates all app cards for each installed HubSpot account (you cannot gate individual cards).
• Use the hs-release-app-cards feature flag for testing and gradual rollout:
• Turn it ON only for specific tests or beta portals by setting their portal-level flagState to ON while keeping other installs OFF.
• To roll out to new installs only, batch-set all existing installs to OFF, then set the flag’s defaultState to ON so new installs automatically see app cards.
• Expand access over time by switching additional portals to ON in batches until all installs are migrated.
• After rollout, delete the hs-release-app-cards feature flag so app cards are no longer gated.
• Before running the View Swapping Tool, confirm the flag has been deleted so replacement app cards are visible everywhere the migration will apply.

Note: To publish your app in the App Marketplace for the first time or to apply for certification if you already have a Marketplace-listed app, you must migrate and remove any legacy CRM cards and meet the Marketplace certification requirements and listing requirements.

Migrate Customer Views
Call the Migrate Views API once your replacement card is completed. Listed below are the required parameters:

• appId
• legacyCrmCardId
• appCardId
• helpdeskAppCardId (if applicable)
• Developer API key/OAuth token with sufficient permissions for the app.

This migration runs asynchronously across all installs. HubSpot will process the view updates asynchronously.

Example Response:

After the migration, the legacy CRM cards will no longer be visible and will be replaced by the app card. You can then safely remove the legacy card from your source code. If you do not remove it, the legacy CRM card will be automatically hidden from customers on October 31st, 2026, when the deprecation of legacy cards officially takes effect.

Note: End-user configuration is unnecessary. The existing card views will remain completely intact, ensuring that end-users experience no disruption, such as card loss or view resets, when your app card is implemented.

Standardized Memberships Error Messaging

Login failures for password-protected pages and memberships now return a single generic error message instead of multiple messages corresponding to the specific authentication issue.

What's changing?

Previously, Content Hub Professional and Content Hub Enterprise users could see different error messages depending on whether an email address existed or a password was incorrect. This created an inconsistent experience and could unintentionally expose account-related signals. This update improves security and delivers a more consistent login experience.

How it works

• All failed login attempts now return the same response, regardless of the underlying cause.
• Users will see a single message: “Invalid email or password.”
• No distinction is made between different authentication failures (e.g., incorrect email vs incorrect password)
• Existing login flows remain unchanged aside from this unified messaging.

This update is applied automatically, and no setup or migration is required.

Client Secret Rotation Now Available in Developer Platform UI

App owners can now rotate their app's client secret directly from the HubSpot developer platform UI with no support ticket required.

What's changing?

A new Rotate button now appears next to the client secret in the app's auth settings. Clicking it triggers a confirmation modal that requires you to type your app's name before proceeding. Once confirmed, the old secret is immediately invalidated, and a new one is generated.

Client secret rotation is available in:

• Legacy public apps: Developer portal > Auth tab
• Project-based apps: Projects > App Details > Client Credentials
• MCP Auth apps: MCP Connectors > Client Credentials

Why it matters

A leaked client secret can allow an attacker to create or generate OAuth tokens indefinitely. Previously, rotating a secret required opening a support ticket, a process that could take hours or days. This feature enables immediate, self-service response to security incidents.

Action required

No action is required at this time. If your app's client secret is compromised, you can now rotate it directly in your app's settings.

Custom Channels API: New sender and contact association options for outgoing messages

The Custom Channels API v2026-03 adds two new optional fields on outgoing messages: associateWithContactId and senderActorId. These fields give integrations more explicit control over which contact is linked to a thread and which actor is recorded as the sender of a message.

What's changing?

associateWithContactId
Channels using the CHANNEL_SPECIFIC_OPAQUE_ID delivery identifier type can now pass a HubSpot contact record ID when sending the first outgoing message of a thread via POST /conversations/custom-channels/2026-03/{channelId}/messages.

Example of associateWithContactId:

Constraints: only applies to CHANNEL_SPECIFIC_OPAQUE_ID channels; only takes effect on the first OUTGOING message of a thread; the contact ID is validated and must exist; requests on any other message type will be rejected. Channels using email or phone identifier types continue to resolve contact associations automatically.

senderActorId : All outgoing messages now accept an optional senderActorId field to record which actor (for example, a support rep, integration, or external chatbot) sent the message.

• Type: string
• Format: Conversations actor ID, such as:
• A-12345 (HubSpot agent user)
• I-67890 (integration)
• Scope: available across all delivery identifier types on outgoing messages.

When provided, senderActorId is used to attribute the message to that actor in Conversations (for example, which rep is shown as the sender). Example of a valid outgoing message with senderActorId:

If senderActorId is missing, invalid, or used in the wrong context, the API returns HTTP 400 with a VALIDATION_ERROR response using the standard HubSpot error envelope. The most important cases are when using senderActorId on an INCOMING message. senderActorId is only allowed for outgoing messages. Including it on an INCOMING message will be rejected. Error example:

Personalized app and agent recommendations with Breeze Assistant

Users can now ask Breeze Assistant to recommend marketplace apps based on criteria entered, and refine the results with follow-up questions. Users can describe a business need in plain language and get pointed in the right direction, refining with follow-up questions until they land on the right fit, and find the right app faster and with confidence. See this product update for more details.

HubSpot CLI v8.4.0 Introduces Project Management Commands and UX Improvements

The latest HubSpot CLI version, 8.4.0, release adds two new commands, hs project info and hs project delete, enabling developers and AI agents to retrieve project metadata, generate install URLs, and delete apps directly from the CLI. The release also improves the developer experience with profile selection prompts when --profile is omitted and introduces an updated logging UI for supported terminals.

Several bugs have been addressed, including fixes for incorrect srcDir comparisons in hs project dev, improved profile error handling for 2025.1 projects, and issues affecting serverless function detection and local development.

For a complete list of available commands, check out the reference documentation.

Public Betas

Workflow action to change contact participant state for a marketing event

You can now automatically mark contacts’ participant state on manually created Marketing Events using a new workflow action.

With this workflow action, automatically mark contacts as:

• Registered
• Attended
• Canceled

Previously, businesses that relied on marketing events for lead generation and nurturing couldn't directly change contacts participation status for a marketing event. This update streamlines and automates that process. This workflow action is available for Pro+ customers. Learn more in the Product Update.

HubSpot IP Ranges Notifications

Introducing email notifications for HubSpot IP range changes. Customers can now subscribe to receive notifications when HubSpot’s published IP ranges are added, modified, or removed, allowing them to proactively update their firewall rules and network configurations.

Super admins can subscribe to email notifications via Settings → Notification Preferences → Security → IP Range Updates.

Questions or comments? Please join us in our developer forums.