Refresh a Hex Notebook After a Warehouse Load

Most Hex notebooks refresh on a timer and hope the warehouse loaded first. When the load runs late, the notebook recomputes on stale tables and publishes yesterday's numbers with today's date. This blueprint removes the guess: the ingestion step and the Hex refresh live in one Kestra execution, so io.kestra.plugin.hex.projects.Run only starts once the data has actually landed, waits for the notebook to finish, and Slack gets the run status with a direct link.

How it works

1. load_warehouse stands in for your ingestion. It is a plain Log task here so the flow runs anywhere; in production you replace it with a real load such as the dlt REST API to DuckDB blueprint or a Trino batch, keeping the refresh chained behind it.
2. refresh_notebook (io.kestra.plugin.hex.projects.Run) calls the Hex API with the project ID, polls every ten seconds, and blocks until the run reaches a terminal state because wait is true.
3. The task exposes status, runUrl, runId, projectVersion, and timing attributes as outputs; notify_team interpolates the status and the run URL into a Slack message.
4. The errors block posts a distinct alert whether the load or the notebook run failed, and the execution view shows which half broke.
5. A disabled-by-default Schedule trigger runs the whole chain at 05:30 so numbers are fresh before standup.

What you get

• A dashboard that refreshes when data lands, not on a blind timer that races the load.
• The Hex run status and URL as first-class flow outputs, ready for notifications or downstream conditions.
• One execution history entry that answers whether the data loaded, whether the notebook ran, and who was told.
• A chain where swapping the ingestion half changes one task, not the architecture.

Who it's for

• Analytics engineers who own both the load and the notebook and are tired of stitching their timing together by hand.
• Data teams whose stakeholders screenshot Hex dashboards into decks and need those numbers to be current.
• Anyone who has debugged a "wrong numbers" report that turned out to be a refresh racing an ingestion job.

Why orchestrate this with Kestra

Hex can schedule its own refreshes, but it cannot see your warehouse loads. Kestra sequences the two with explicit dependencies: the refresh starts only after the load succeeds, wait: true turns the notebook run into a real pipeline step with a status, and failures page Slack instead of leaving a stale dashboard up silently. The unchanged Hex project just gets called at the right moment.

Prerequisites

• A Hex project and its project ID, visible in the project URL.
• A Hex API token with permission to run the project.
• A Slack incoming webhook for refresh reports.

Secrets

• HEX_API_TOKEN: Hex API token used to run the project.
• SLACK_WEBHOOK_URL: Slack incoming webhook URL.

Quick start

1. Add the HEX_API_TOKEN and SLACK_WEBHOOK_URL secrets to your Kestra namespace.
2. Set the project_id input to a real Hex project and execute the flow.
3. Check Slack for the status and run URL, then replace load_warehouse with your real ingestion and enable the daily trigger.

How to extend

• Replace the stand-in load with the dlt REST API to DuckDB blueprint, a Trino query, or any warehouse task, and keep the refresh chained behind it.
• Pass inputParams to the Run task to point the notebook at the dataset or date the load just produced.
• Fan out to several projects by wrapping the Run task in a Loop over project IDs, as shown in the parameterized regional reports blueprint.
• Tighten maxDuration to page when the notebook runs long, as shown in the notebook SLA guard blueprint.

Links

• Hex plugin documentation
• Hex documentation