Files
zitadel/apps/docs/content/guides/integrate/actions/testing-request-signature.mdx
T
545e2665f3 docs: fix code block styling by migrating to native fumadocs-ui components (#11646)
# Which Problems Are Solved

- Docs code blocks that display imported files (YAML configs, Go
examples) render as unstyled plain text with no syntax highlighting,
unlike fenced code blocks which go through `rehypeCode`/Shiki

# How the Problems Are Solved

- Deleted `components/docusaurus/code-block.tsx` entirely — no custom
wrapper is needed anymore
- Replaced all usages with `DynamicCodeBlock` from
`fumadocs-ui/components/dynamic-codeblock` directly in MDX files; it
handles SSR pre-rendering through the same Shiki pipeline as all other
code blocks
- Raw file content (YAML, Go) is imported as strings via webpack's
existing `asset/source` rule already configured in `next.config.mjs` —
no new infrastructure required
- In `_proxy_guide_tls_mode.mdx`, the `Commands` JSX component was
refactored from concatenated JSX array children to a single template
literal string, which is what `DynamicCodeBlock` (and any string-based
highlighter) requires
- All changes applied to both non-versioned docs and versioned snapshots
(v4.10, v4.11)

# Additional Changes

None.

# Additional Context

- Affected MDX files: YAML config files under
`self-hosting/manage/configure/`, reverse-proxy guides,
`self-hosting/deploy/compose.mdx`, and the actions
`testing-request-signature.mdx` guide

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>code block style is weird</issue_title>
> <issue_description>### Preflight Checklist
> 
> - [x] I could not find a solution in the existing issues, docs, nor
discussions
> - [x] I have joined the [ZITADEL chat](https://zitadel.com/chat)
> 
> ### Describe the docs your are missing or that are wrong
> 
> This hurts my eyes:
> 
> <img width="867" height="525" alt="Image"
src="https://github.com/user-attachments/assets/b7b66d92-56e1-4e0a-8dba-3cab448930fe"
/>
> 
> ### Additional Context
> 
> _No response_</issue_description>
> 
> <agent_instructions>the user reported a weirdly styled code block in
the docs page where we used to display yaml files. Investigate the docs
and fix the styling</agent_instructions>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> <comment_new><author>@fforootd</author><body>
> haha, ok that is certainly weird, let me look at
that.</body></comment_new>
> </comments>
> 


</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes zitadel/zitadel#11645

<!-- START COPILOT CODING AGENT TIPS -->

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: fforootd <[email protected]>
Co-authored-by: Florian Forster <[email protected]>
2026-02-20 06:46:32 +05:30

241 lines
8.6 KiB
Plaintext

---
title: Verify Payload Integrity
---
import JsonGo from './go/json.go';
import JwtGo from './go/jwt.go';
import JweGo from './go/jwe.go';
import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock';
This guide shows you how to verify the integrity of the received data on your target.
There are three options available, which will be demonstrated in the following sections.
The examples are based on the request action, but the same principles apply to other action types as well.
## Prerequisites
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
<Callout type="info">
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
In case you are using a different setup, you need to adjust the target URL accordingly and will need to make sure that the target is reachable from ZITADEL.
</Callout>
## Payload and Validation Types
ZITADEL supports the following three types of payload in actions:
- **JSON**: The payload is sent as JSON in the request body. Additionally, a signature header is sent to validate the payload.
This is the simplest form of payload and validation and doesn't require any additional calls to validate the payload. It's also the default type,
which will be used if no type is specified.
- **JWT**: The payload is sent as a JSON Web Token (JWT) in the request body. The JWT is signed with the signing key of the instance.
This allows you to validate the payload by verifying the signature of the JWT using the signing key managed though the webkeys endpoint of the ZITADEL instance,
which allows for easier key rotation and management. Additionally, it's the base for the JWE type, in case you need to encrypt the payload for certain use cases.
- **JWE**: The payload is sent as encrypted JSON Web Token (JWE) in the request body. The JWT is additionally encrypted with the public key provided by you.
This allows you to validate and decrypt the payload by verifying the signature of the JWT using the signing key managed though the webkeys endpoint of the ZITADEL instance,
and decrypting the payload using your private key. This is the most secure form of payload and validation, but requires additional setup to provide the public key to ZITADEL.
This type is recommended if the payload contains sensitive information that should not be exposed to any intermediaries.
## Create target
We'll start the endpoint on port '8090' and if we want to use it as webhook, the target can be created as follows:
See [Create a target](/apis/resources/action_service_v2/action-service-create-target) for more detailed information.
Specify the `payloadType` according to the implementation you want to test: `PAYLOAD_TYPE_JSON`, `PAYLOAD_TYPE_JWT`, or `PAYLOAD_TYPE_JWE`.
```shell
curl -L -X POST 'https://${CUSTOM_DOMAIN}/v2/actions/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",
"payloadType": "PAYLOAD_TYPE_JSON"
}'
```
Example response after creating the target:
```json
{
"id": "344649040681500814",
"creationDate": "2025-10-31T15:00:36.432595dZ",
"signingKey": "somekey"
}
```
Save the returned ID to set in the execution. If you're intending to use the `PAYLOAD_TYPE_JSON`, additionally store the `signingKey` and use it in the example above.
### JWE Specific Setup
If you are using the `PAYLOAD_TYPE_JWE`, you need to provide a public key to ZITADEL so that it can encrypt the payload.
Create a public/private key pair. You can use the following command to generate an RSA key pair:
```shell
openssl genpkey -algorithm RSA -outform PEM -out private_key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in private_key.pem -out public_key.pem
```
Then upload the public key to ZITADEL using the following command. Replace `<TargetID>` with the ID of the target you created earlier.
Use the base64 encoded content of the `public_key.pem` file as the value for `publicKey`.
```shell
curl -L -X POST 'https://${CUSTOM_DOMAIN}/v2/actions/targets/<TargetID>/publickeys' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"publicKey": "<base64 encoded contents of public_key.pem>"
}'
```
Be sure to also activate the public key for the target using the returned `<KeyID>` from the previous request:
```shell
curl -L -X PUT 'https://${CUSTOM_DOMAIN}/v2/actions/targets/<TargetID>/publickeys/<KeyID>/activate' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```
## Set execution
To configure ZITADEL to call the target when an API endpoint is called, you need to set an execution and define the request
condition.
See [Set an execution](/apis/resources/action_service_v2/action-service-set-execution) for more detailed information.
```shell
curl -L -X PUT 'https://${CUSTOM_DOMAIN}/v2/actions/executions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"condition": {
"request": {
"method": "/zitadel.user.v2.UserService/CreateUser"
}
},
"targets": [
"<TargetID returned>"
]
}'
```
## Start example target
To test the actions feature, you need to create a target that will be called when an API endpoint is called.
You will need to implement a listener that can receive HTTP requests.
For this example, we will use a simple Go HTTP server that will print the received request to standard output.
As mentioned before, this validation can and should be applied to any target implementation.
<Tabs>
<Tab value="JSON">
<DynamicCodeBlock lang="go" code={JsonGo} />
</Tab>
<Tab value="JWT">
<DynamicCodeBlock lang="go" code={JwtGo} />
</Tab>
<Tab value="JWE">
<DynamicCodeBlock lang="go" code={JweGo} />
</Tab>
</Tabs>
<Callout type="info">
The example above runs only on your local machine (`localhost`).
To test it with Zitadel, you must make your listener reachable from the internet.
You can do this by using **Webhook.site** (see [Creating a Listener with Webhook.site](./webhook-site-setup)).
</Callout>
## Example call
Now that you have set up the target and execution, you can test it by creating a user through the Management Console UI or
by calling the ZITADEL API to create a user.
```shell
curl -L -X POST 'https://${CUSTOM_DOMAIN}/v2/users/new' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"organizationId": "344648897353810062",
"human":
{
"profile":
{
"givenName": "Minnie",
"familyName": "Mouse",
"nickName": "Mini",
"displayName": "Minnie Mouse",
"preferredLanguage": "en",
"gender": "GENDER_FEMALE"
},
"email":
{
"email": "[email protected]"
}
}
}'
```
Your server should now print out something like the following. Check out
the [Sent information Request](./usage#sent-information-request) payload description.
```json
{
"fullMethod": "/zitadel.user.v2.UserService/CreateUser",
"instanceID": "344648897353744526",
"orgID": "344648897353810062",
"projectID": "344648897353875598",
"userID": "344648897354465422",
"request":
{
"organizationId": "344648897353810062",
"human":
{
"profile":
{
"givenName": "Minnie",
"familyName": "Mouse",
"nickName": "Mini",
"displayName": "Minnie Mouse",
"preferredLanguage": "en",
"gender": "GENDER_FEMALE"
},
"email":
{
"email": "[email protected]"
}
}
},
"headers":
{
"Content-Type":
[
"application/grpc"
],
"Host":
[
"localhost:8080"
],
"X-Forwarded-For":
[
"::1"
],
"X-Forwarded-Host":
[
"localhost:8080"
]
}
}
```
## Conclusion
You have successfully set up a target and verified the payload integrity for request actions using your preferred payload type.
You can now extend this setup to other action types and integrate it into your workflows as needed.
Selecting the appropriate payload type ensures that your data is transmitted securely and can be validated effectively on the receiving end.
Find more information about the actions feature in the [API documentation](/concepts/features/actions_v2).