BetaActionServiceApi

Deprecated: Please move to the corresponding endpoints under Action Service v2. This service will be removed in the next major version of ZITADEL.

Overview

The BetaActionServiceApi provides methods for managing targets (webhooks/functions) and executions (when to trigger them) in ZITADEL.

Initialization

require 'zitadel/client'

client = Zitadel::Client::ApiClient.new
client.config.access_token = 'your_access_token'

action_service = Zitadel::Client::Api::BetaActionServiceApi.new(client)

Key Concepts

Target: A webhook endpoint or function to call
Execution: Configuration for when to call targets (trigger conditions)
Condition: Service/method/function that triggers the execution

Key Methods

Target Management

create_target - Create webhook target

beta_action_service_create_target_request

object

required

Target configuration

Show properties

name

string

required

Target name

endpoint

string

required

Webhook URL

timeout

string

Request timeout (e.g., ”10s”)

async

boolean

Execute asynchronously

request = Zitadel::Client::Models::BetaActionServiceCreateTargetRequest.new(
  name: 'User Registration Webhook',
  endpoint: 'https://myapp.com/webhooks/user-registered',
  timeout: '10s',
  async: true
)

response = action_service.create_target(request)
puts "Target ID: #{response.id}"

Required Permission: action.target.writeReturns: BetaActionServiceCreateTargetResponse

get_target - Get target details

request = Zitadel::Client::Models::BetaActionServiceGetTargetRequest.new(
  target_id: '123456789'
)

response = action_service.get_target(request)
puts "Target: #{response.target.name}"
puts "Endpoint: #{response.target.endpoint}"

Required Permission: action.target.readReturns: BetaActionServiceGetTargetResponse

list_targets - List all targets

beta_action_service_list_targets_request

object

required

Search and pagination

request = Zitadel::Client::Models::BetaActionServiceListTargetsRequest.new(
  limit: 50
)

response = action_service.list_targets(request)

response.result.each do |target|
  puts "Target: #{target.name}"
  puts "  Endpoint: #{target.endpoint}"
  puts "  Async: #{target.async}"
end

Required Permission: action.target.readReturns: BetaActionServiceListTargetsResponse

update_target - Update target configuration

request = Zitadel::Client::Models::BetaActionServiceUpdateTargetRequest.new(
  target_id: '123456789',
  name: 'Updated Webhook Name',
  endpoint: 'https://myapp.com/webhooks/v2/user-registered',
  timeout: '15s'
)

action_service.update_target(request)

Required Permission: action.target.writeReturns: BetaActionServiceUpdateTargetResponse

delete_target - Delete a target

Deletes target and removes it from all executions.

request = Zitadel::Client::Models::BetaActionServiceDeleteTargetRequest.new(
  target_id: '123456789'
)

action_service.delete_target(request)

Required Permission: action.target.deleteReturns: BetaActionServiceDeleteTargetResponse

Execution Management

set_execution - Configure when to call targets

beta_action_service_set_execution_request

object

required

Execution configuration

Show properties

condition

object

required

When to trigger (service/method/function)

targets

array

required

Target IDs or execution includes

# Call target when user is created
request = Zitadel::Client::Models::BetaActionServiceSetExecutionRequest.new(
  condition: {
    request: {
      method: '/zitadel.user.v2.UserService/AddHumanUser'
    }
  },
  targets: [
    { target_id: '123456789' }
  ]
)

action_service.set_execution(request)

Setting an empty targets array removes all targets (makes it a no-op).

Required Permission: action.execution.writeReturns: BetaActionServiceSetExecutionResponse

list_executions - List execution configurations

request = Zitadel::Client::Models::BetaActionServiceListExecutionsRequest.new

response = action_service.list_executions(request)

response.result.each do |execution|
  puts "Condition: #{execution.condition}"
  puts "Targets: #{execution.targets.map(&:target_id).join(', ')}"
end

Required Permission: action.execution.readReturns: BetaActionServiceListExecutionsResponse

Discovery Methods

list_execution_services - List available services

Returns all services that can be used as conditions.

request = {}

response = action_service.list_execution_services(request)

response.services.each do |service|
  puts "Service: #{service}"
end

Returns: BetaActionServiceListExecutionServicesResponse

list_execution_methods - List service methods

Returns all methods that can trigger executions.

request = {}

response = action_service.list_execution_methods(request)

response.methods.each do |method|
  puts "Method: #{method}"
end

Returns: BetaActionServiceListExecutionMethodsResponse

list_execution_functions - List available functions

Returns all functions that can be used as conditions.

request = {}

response = action_service.list_execution_functions(request)

response.functions.each do |function|
  puts "Function: #{function}"
end

Returns: BetaActionServiceListExecutionFunctionsResponse

Execution Conditions

Request Condition (Method-based)

Trigger on specific API method calls:

condition: {
  request: {
    method: '/zitadel.user.v2.UserService/AddHumanUser'
  }
}

Common methods:

/zitadel.user.v2.UserService/AddHumanUser - User creation
/zitadel.user.v2.UserService/DeactivateUser - User deactivation
/zitadel.session.v2.SessionService/CreateSession - Session creation
/zitadel.oidc.v2.OIDCService/CreateCallback - OIDC callback

Response Condition

Trigger on specific method responses:

condition: {
  response: {
    method: '/zitadel.user.v2.UserService/AddHumanUser'
  }
}

Function Condition

Trigger on specific events:

condition: {
  function: 'user.created'
}

Event Condition

Trigger on event type:

condition: {
  event: {
    event: 'user.human.added'
  }
}

Target Configuration

HTTP Webhook

{
  name: 'My Webhook',
  endpoint: 'https://api.example.com/webhook',
  timeout: '10s',
  async: true,
  interrupt_on_error: false
}

With Authentication

{
  name: 'Authenticated Webhook',
  endpoint: 'https://api.example.com/webhook',
  target_type: 'webhook',
  http_config: {
    headers: {
      'Authorization' => 'Bearer secret_token',
      'X-API-Key' => 'api_key_value'
    }
  }
}

Use Cases

User Registration Webhook

# 1. Create target
target_request = Zitadel::Client::Models::BetaActionServiceCreateTargetRequest.new(
  name: 'User Registration Webhook',
  endpoint: 'https://myapp.com/webhooks/user-registered',
  async: true
)

target = action_service.create_target(target_request)

# 2. Set execution to trigger on user creation
exec_request = Zitadel::Client::Models::BetaActionServiceSetExecutionRequest.new(
  condition: {
    request: {
      method: '/zitadel.user.v2.UserService/AddHumanUser'
    }
  },
  targets: [
    { target_id: target.id }
  ]
)

action_service.set_execution(exec_request)

puts "Webhook will be called when users are created"

Audit Logging

# Create audit webhook
target = action_service.create_target(
  Zitadel::Client::Models::BetaActionServiceCreateTargetRequest.new(
    name: 'Audit Logger',
    endpoint: 'https://audit.example.com/log',
    async: true
  )
)

# Log all user operations
user_methods = [
  '/zitadel.user.v2.UserService/AddHumanUser',
  '/zitadel.user.v2.UserService/DeactivateUser',
  '/zitadel.user.v2.UserService/DeleteUser',
  '/zitadel.user.v2.UserService/LockUser'
]

user_methods.each do |method|
  action_service.set_execution(
    Zitadel::Client::Models::BetaActionServiceSetExecutionRequest.new(
      condition: { response: { method: method } },
      targets: [{ target_id: target.id }]
    )
  )
end

Multi-Target Execution

# Create multiple targets
slack_target = action_service.create_target(...)
email_target = action_service.create_target(...)
audit_target = action_service.create_target(...)

# Call all targets on user creation
action_service.set_execution(
  Zitadel::Client::Models::BetaActionServiceSetExecutionRequest.new(
    condition: {
      request: {
        method: '/zitadel.user.v2.UserService/AddHumanUser'
      }
    },
    targets: [
      { target_id: slack_target.id },
      { target_id: email_target.id },
      { target_id: audit_target.id }
    ]
  )
)

Cleanup Old Targets

# List all targets
request = Zitadel::Client::Models::BetaActionServiceListTargetsRequest.new
targets = action_service.list_targets(request)

# Delete unused targets
targets.result.each do |target|
  # Check if target is used in any execution
  executions = action_service.list_executions(
    Zitadel::Client::Models::BetaActionServiceListExecutionsRequest.new
  )
  
  in_use = executions.result.any? do |exec|
    exec.targets.any? { |t| t.target_id == target.id }
  end
  
  unless in_use
    action_service.delete_target(
      Zitadel::Client::Models::BetaActionServiceDeleteTargetRequest.new(
        target_id: target.id
      )
    )
    puts "Deleted unused target: #{target.name}"
  end
end

Webhook Payload

Webhooks receive JSON payload with:

{
  "fullMethod": "/zitadel.user.v2.UserService/AddHumanUser",
  "instanceId": "123456",
  "organizationId": "789012",
  "projectId": "345678",
  "userId": "901234",
  "request": { ... },
  "response": { ... },
  "metadata": { ... }
}

Required Permissions

action.target.read - Read targets
action.target.write - Create/modify targets
action.target.delete - Delete targets
action.execution.read - Read executions
action.execution.write - Configure executions

Migration Guide

To migrate to Action Service v2:

Replace BetaActionServiceApi with ActionServiceV2Api
Update target configuration format
Review execution condition structure
Test webhook payloads

Client

Stable APIs

Beta APIs

Models

Overview

Initialization

Key Concepts

Key Methods

Target Management

Execution Management

Discovery Methods

Execution Conditions

Request Condition (Method-based)

Response Condition

Function Condition

Event Condition

Target Configuration

HTTP Webhook

With Authentication

Use Cases

User Registration Webhook

Audit Logging

Multi-Target Execution

Cleanup Old Targets

Webhook Payload

Required Permissions

Migration Guide

See Also

Build docs developers (and LLMs) love

Client

Stable APIs

Beta APIs

Models

​Overview

​Initialization

​Key Concepts

​Key Methods

​Target Management

​Execution Management

​Discovery Methods

​Execution Conditions

​Request Condition (Method-based)

​Response Condition

​Function Condition

​Event Condition

​Target Configuration

​HTTP Webhook

​With Authentication

​Use Cases

​User Registration Webhook

​Audit Logging

​Multi-Target Execution

​Cleanup Old Targets

​Webhook Payload

​Required Permissions

​Migration Guide

​See Also

Build docs developers (and LLMs) love

Overview

Initialization

Key Concepts

Key Methods

Target Management

Execution Management

Discovery Methods

Execution Conditions

Request Condition (Method-based)

Response Condition

Function Condition

Event Condition

Target Configuration

HTTP Webhook

With Authentication

Use Cases

User Registration Webhook

Audit Logging

Multi-Target Execution

Cleanup Old Targets

Webhook Payload

Required Permissions

Migration Guide

See Also