Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zitadel/zitadel/llms.txt

Use this file to discover all available pages before exploring further.

Creates a new target that points to your external endpoint. Targets can be used in executions to extend ZITADEL’s functionality.

​
HTTP Request

POST /v2/actions/targets

​
Permissions

Requires action.target.write permission.

​
Request Body

​
name
string
required
Display name for the target (1-1000 characters).
​
target_type
object
required
Defines how the response is handled. Choose one:
​
rest_webhook
object
POST request where only the status code is checked. Body is ignored.
​
interrupt_on_error
boolean
If true, execution stops on non-2xx response. Default is false.
​
rest_call
object
POST request where status code and body are checked. Allows payload modification.
​
interrupt_on_error
boolean
If true, execution stops on non-2xx response. Default is false.
​
rest_async
object
Asynchronous POST request. Response is not waited for or checked. Use for events.
​
timeout
string
Duration until ZITADEL cancels the request (e.g., ”10s”). Maximum is 270 seconds. If the target doesn’t respond before timeout, the connection is closed and the action fails.
​
endpoint
string
required
The URL of the endpoint to call (1-2048 characters). Must be a valid HTTPS URL.
​
payload_type
enum
How the payload is formatted and secured:
  • PAYLOAD_TYPE_JSON (default): JSON with X-ZITADEL-Signature header
  • PAYLOAD_TYPE_JWT: Signed JWT in the body
  • PAYLOAD_TYPE_JWE: Encrypted JWT in the body (requires public key)

​
Response

​
id
string
Unique identifier of the newly created target.
​
creation_date
timestamp
When the target was created.
​
signing_key
string
Key used to sign and verify payloads sent to the target. Used to calculate the HMAC SHA256 signature in the X-ZITADEL-Signature header. Keep this secret.

​
Example Request

curl -X POST 'https://api.zitadel.cloud/v2/actions/targets' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ip_allow_list",
    "rest_webhook": {
      "interrupt_on_error": true
    },
    "timeout": "10s",
    "endpoint": "https://example.com/hooks/ip_check",
    "payload_type": "PAYLOAD_TYPE_JSON"
  }'

​
Example Response

{
  "id": "69629012906488334",
  "creation_date": "2024-12-18T07:50:47.492Z",
  "signing_key": "98KmsU67"
}

​
Error Responses

Status CodeDescription
400Feature flag actions not enabled or invalid request
401Unauthorized - missing or invalid authentication
403Forbidden - insufficient permissions
409Target with this name already exists

​
Payload Types

​
JSON (Default)

Payload is sent as JSON in the request body. Signature is included in the X-ZITADEL-Signature header, calculated using HMAC SHA256 over the raw body. Verify the signature on your endpoint: 
const crypto = require('crypto');

function verifySignature(body, signature, signingKey) {
  const hmac = crypto.createHmac('sha256', signingKey);
  hmac.update(body);
  const calculatedSignature = hmac.digest('hex');
  return signature === calculatedSignature;
}

​
JWT

Payload is sent as a signed JWT. The signature can be verified using ZITADEL’s public keys from the JWKS endpoint.

​
JWE

Payload is sent as an encrypted JWT. You must add your public key to the target for encryption. This provides additional security for sensitive data.

​
Notes

  • The signing key is only returned on creation and cannot be retrieved later
  • Store the signing key securely - it’s needed to verify request authenticity
  • Targets can be updated later, but the signing key only changes when explicitly rotated
  • The endpoint URL must be accessible from ZITADEL servers
  • For rest_async targets, timeouts only affect the individual target, not the overall execution

Build docs developers (and LLMs) love

Get started for freeTalk to us