zitadel/docs/docs/apis/actions/v3/testing-locally.md

title

title
Test Actions Locally

In this guide, you will create a ZITADEL execution and target. After a user is created through the API, the target is called.

Prerequisites

Before you start, make sure you have everything set up correctly.

• You need to be at least a ZITADEL IAM_OWNER
• Your ZITADEL instance needs to have the actions feature enabled.

Start example target

To start a simple HTTP server locally, which receives the webhook call, the following code example can be used:

package main

import (
	"fmt"
	"io"
	"net/http"
)

// webhook HandleFunc to read the request body and then print out the contents
func webhook(w http.ResponseWriter, req *http.Request) {
	// read the body content
	sentBody, err := io.ReadAll(req.Body)
	if err != nil {
		// if there was an error while reading the body return an error
		http.Error(w, "error", http.StatusInternalServerError)
		return
	}
	// print out the read content
	fmt.Println(string(sentBody))
}

func main() {
	// handle the HTTP call under "/webhook"
	http.HandleFunc("/webhook", webhook)

	// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
	http.ListenAndServe(":8090", nil)
}

What happens here is only a target which prints out the received request, which could also be handled with a different logic.

Create target

As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the target can be created as follows:

Create a target

curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/targets' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "name": "local webhook",
  "restWebhook": {
    "interruptOnError": true    
  },
  "endpoint": "http://localhost:8090/webhook",
  "timeout": "10s"
}'

Save the returned ID to set in the execution.

Set execution

To call the target just created before, with the intention to print the request used for user creation by the user V2 API, we define an execution with a method condition.

Set an execution

curl -L -X PUT 'https://$CUSTOM-DOMAIN/v3alpha/executions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "condition": {
        "request": {
            "method": "/zitadel.user.v2.UserService/AddHumanUser"
        }
    },
    "targets": [
        {
            "target": "<TargetID returned>"
        }
    ]
}'

Example call

Now on every call on /zitadel.user.v2.UserService/AddHumanUser the local server prints out the received body of the request:

curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "profile": {
        "givenName": "Example_given",
        "familyName": "Example_family"
    },
    "email": {
        "email": "[email protected]"
    }
}'

Should print out something like, also described under Sent information Request:

{
  "fullMethod": "/zitadel.user.v2.UserService/AddHumanUser",
  "instanceID": "262851882718855632",
  "orgID": "262851882718921168",
  "projectID": "262851882719052240",
  "userID": "262851882718986704",
  "request": {
    "profile": {
      "given_name": "Example_given",
      "family_name": "Example_family"
    },
    "email": {
      "email": "[email protected]"
    }
  }
}