Hex Webhooks & Events
Overview
Hex doesn't provide push webhooks. For event-driven integrations, poll run status or build your own notification system around run completions.
Instructions
Run Status Polling with Callback
async function runWithCallback(
client: HexClient,
projectId: string,
params: Record<string, any>,
onComplete: (result: any) => void,
onError: (error: Error) => void
) {
try {
const { runId } = await client.runProject(projectId, params);
const poll = async () => {
const status = await client.getRunStatus(projectId, runId);
if (status.status === 'COMPLETED') { onComplete(status); return; }
if (status.status === 'ERRORED' || status.status === 'KILLED') { onError(new Error(status.status)); return; }
setTimeout(poll, 5000);
};
poll();
} catch (err) { onError(err as Error); }
}
Notify on Completion
runWithCallback(client, 'project-id', { date: '2025-01-01' },
(result) => {
// Send Slack notification, email, etc.
fetch(process.env.SLACK_WEBHOOK_URL!, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ text: `Hex project completed: ${result.runId}` }),
});
},
(error) => console.error('Run failed:', error)
);
Prerequisites
- A secret-manager webhook secret, origin allowlist, replay-window policy, and opaque event ledger.
- A sandbox receiver plus a tested disable/cancel control for downstream project execution.
Output
Return an event receipt with type, opaque event/run ID, signature/timestamp result, idempotency outcome, queue state, canary result, and rollback reference. Exclude payload data, SQL, output, and signatures.
Error Handling
Reject unknown origin, stale/replayed delivery, malformed payload, unknown project destination, or non-idempotent retry. Quarantine the opaque event and disable the consumer if integrity is uncertain.
Examples
type=run.completed; event=evt-opaque-9; signature=pass; replay=absent; project=proj-sandbox-12; enqueue=once; rollback=consumer-disabled proves the event boundary.