hatchet-dev · mrkaye97 · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/api-contracts/v1/workflows.proto b/api-contracts/v1/workflows.proto
@@ -111,8 +111,18 @@ message CreateWorkflowVersionRequest {
     repeated Concurrency concurrency_arr = 12; // (optional) the workflow concurrency options
     repeated DefaultFilter default_filters = 13; // (optional) the default filters for the workflow
     optional bytes input_json_schema = 14; // (optional) the JSON schema for the workflow input
+
+    optional IdempotencyConfig idempotency = 15; // (optional) idempotency configuration for the workflow
+}
+
+message IdempotencyConfig {
+    string expression = 1; // a CEL expression for determining the idempotency key for workflow runs
+    int64 ttl_ms = 2; // time-to-live for idempotency keys in milliseconds
 }
 
+message IdempotencyCollisionError {
+    string existing_run_external_id = 1; // the external ID of the existing workflow run that caused the collision
+}
 
 message DefaultFilter {
     string expression = 1; // (required) the CEL expression for the filter

diff --git a/api/v1/server/oas/transformers/v1/events.go b/api/v1/server/oas/transformers/v1/events.go
@@ -77,7 +77,7 @@ func ToV1Event(event *v1.EventWithPayload) gen.V1Event {
 		},
 		Payload:               &payload,
 		SeenAt:                &event.EventSeenAt.Time,
-		Scope:                 &event.EventScope,
+		Scope:                 event.EventScope,
 		TriggeredRuns:         &triggeredRuns,
 		TriggeringWebhookName: event.TriggeringWebhookName,
 	}

diff --git a/cmd/hatchet-migrate/migrate/migrations/20260702180517_v1_0_124.sql b/cmd/hatchet-migrate/migrate/migrations/20260702180517_v1_0_124.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+-- +goose StatementBegin
+ALTER TABLE "WorkflowVersion"
+    ADD COLUMN "idempotencyKeyExpression" TEXT,
+    ADD COLUMN "idempotencyKeyTtlMs" BIGINT
+    ;
+
+ALTER TYPE v1_cel_evaluation_failure_source ADD VALUE IF NOT EXISTS 'IDEMPOTENCY_KEY';
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE "WorkflowVersion"
+    DROP COLUMN "idempotencyKeyExpression",
+    DROP COLUMN "idempotencyKeyTtlMs"
+;
+-- +goose StatementEnd
diff --git a/examples/go/idempotency/trigger.go b/examples/go/idempotency/trigger.go
diff --git a/examples/go/idempotency/trigger/main.go b/examples/go/idempotency/trigger/main.go
diff --git a/examples/go/idempotency/worker.go b/examples/go/idempotency/worker.go
diff --git a/examples/go/idempotency/worker/main.go b/examples/go/idempotency/worker/main.go
diff --git a/examples/python/idempotency/trigger.py b/examples/python/idempotency/trigger.py
diff --git a/examples/python/idempotency/worker.py b/examples/python/idempotency/worker.py
diff --git a/examples/python/worker.py b/examples/python/worker.py
diff --git a/examples/ruby/idempotency/trigger.rb b/examples/ruby/idempotency/trigger.rb