| name | cleanup-workflows |
| description | Audit and remove inactive, test, or deprecated workflows from HubSpot. Identifies workflows that have never enrolled contacts, workflows turned off for 90+ days, and test workflows. |
| license | MIT |
| metadata | {"author":"tomgranot","version":"1.0","category":"ongoing-maintenance"} |
Cleanup Workflows
Audit HubSpot workflows to remove dead weight. Unused workflows clutter the automation dashboard and make it harder to understand what is actually running.
Prerequisites
- HubSpot API token in
.env
- Python with
hubspot-api-client installed via uv
- Note: The Workflows API may return 403 on some plan tiers. If so, audit manually in HubSpot UI under Automation > Workflows.
Step-by-Step Instructions
Stage 1: Before — Inventory All Workflows
Pull all workflows. The Automation API endpoint for workflows:
import requests
headers = {"Authorization": f"Bearer {os.getenv('HUBSPOT_API_TOKEN')}"}
response = requests.get(
"https://api.hubapi.com/automation/v4/flows",
headers=headers,
params={"limit": 100}
)
workflows = response.json()
For each workflow, record: ID, name, enabled status, type, enrollment count, created date, last updated date.
Stage 2: Execute — Identify Candidates for Deletion
Flag workflows matching any of these criteria:
- Turned off for 90+ days with no plans to reactivate
- Zero enrollments ever (likely test or abandoned drafts)
- Test workflows (names containing "test", "temp", "copy of", "draft")
- Superseded workflows replaced by newer versions
- Error state workflows that have been failing consistently
Before deleting, check:
- Does the workflow feed into another workflow (via enrollment trigger)?
- Does the workflow set properties that other workflows depend on?
- Is there any documentation referencing this workflow?
Stage 3: After — Delete and Document
- Turn off workflows first, wait one week, then delete if no issues arise.
- Document deleted workflows in a cleanup log (name, purpose, reason for deletion).
- Notify workflow owners before deletion.
Stage 4: Rollback
- Deleted workflows cannot be restored.
- Before deleting, screenshot or document the workflow logic (triggers, actions, branches) so it can be recreated if needed.
- HubSpot retains workflow activity history on contact records even after the workflow is deleted.
Tips
- Use folders in the workflows dashboard to organize by team, purpose, or status.
- Prefix draft/test workflows with "[TEST]" so they are easy to identify later.
- Review workflows quarterly as part of the database cleanup routine.
