mirror of
https://github.com/zitadel/zitadel.git
synced 2024-12-04 23:45:07 +00:00
docs: Improve http notification doc (#8642)
# Which Problems Are Solved The docs contained typos and links that led to 404. More subejectively the docs did not provide enough guidance for new users what providers are and how to configure an HTTP provider and then activate them. Only basic links to the API docs were given without examples on how to achieve a basic configuration. # How the Problems Are Solved References and typos fixed and reworked the guide. # Additional Changes Added code highlighting for json and bash. # Additional Context We could further improve by adding more help on this page on how to configure SMS and SMTP providers.
This commit is contained in:
mffap
GitHub
parent
e68b5d4a83
commit
87ac5ed254
166
docs/docs/guides/manage/customize/notification-providers.mdx
Normal file
166
docs/docs/guides/manage/customize/notification-providers.mdx
Normal file
@ -0,0 +1,166 @@
|
||||
---
|
||||
title: SMS, SMTP and HTTP Provider for Notifications
|
||||
sidebar_label: Notification Providers
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
ZITADEL can send messages to users via different notification providers, such as SMS, SMTP, or Webhook (HTTP Provider).
|
||||
While you can add multiple providers to different channels, messages will only be delivered via the actived provider.
|
||||
Message and notification texts can be [customized](./texts) for an instance or for each organization.
|
||||
|
||||
## SMS providers
|
||||
|
||||
ZITADEL integrates with Twilio as SMS provider.
|
||||
|
||||
## SMTP providers
|
||||
|
||||
Integration with most SMTP providers is possible through a generic SMTP provider template that allows you to configure custom SMTP providers.
|
||||
Additionally, integration templates are available for:
|
||||
|
||||
- Amazon SES
|
||||
- Mailgun
|
||||
- Mailjet
|
||||
- Postmark
|
||||
- Sendgrid
|
||||
|
||||
:::info Default Provider ZITADEL Cloud
|
||||
A default SMTP provider is configured for ZITADEL Cloud customers.
|
||||
This provider meant for development and testing purposes and you must replace this provider with your custom SMTP provider for production use cases to guarantee security and reliability of your service.
|
||||
:::
|
||||
|
||||
## Webhook / HTTP provider
|
||||
|
||||
Webhook (HTTP Provider) allows you to fully customize the messages and use integrate with any provider or custom solution to deliver the messages to users.
|
||||
A provider with HTTP type will send the messages and the data to a pre-defined webhook as JSON.
|
||||
|
||||
### Configuring a HTTP provider
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="sms" label="SMS" default>
|
||||
|
||||
First [add a new SMS Provider of type HTTP](/apis/resources/admin/admin-service-add-sms-provider-http) to create a new HTTP provider that can be used to send SMS messages:
|
||||
|
||||
```bash
|
||||
curl -L 'https://$CUSTOM-DOMAIN/admin/v1/sms/http' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{
|
||||
"endpoint": "http://relay.example.com/provider",
|
||||
"description": "provider description"
|
||||
}'
|
||||
```
|
||||
|
||||
Where `endpoint` defines the Webhook endpoint to which the data should be sent to.
|
||||
The result will contain an ID of the provider that we need in the next step.
|
||||
|
||||
You can configure multiple SMS providers at the same time.
|
||||
To use the HTTP provider you need to [activate the SMS provider](/apis/resources/admin/admin-service-activate-sms-provider):
|
||||
|
||||
```bash
|
||||
curl -L 'https://$CUSTOM-DOMAIN/admin/v1/sms/:id/_activate' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
The `id` is the provider's ID from the previous step.
|
||||
|
||||
See full API reference for [SMS Providers](/apis/resources/admin/sms-provider) for more details.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="email" label="Email">
|
||||
|
||||
First [add a new Email Provider of type HTTP](/apis/resources/admin/admin-service-add-email-provider-http) to create a new HTTP provider that can be used to send SMS messages:
|
||||
|
||||
```bash
|
||||
curl -L 'https://$CUSTOM-DOMAIN/admin/v1/email/http' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{
|
||||
"endpoint": "http://relay.example.com/provider",
|
||||
"description": "provider description"
|
||||
}'
|
||||
```
|
||||
|
||||
Where `endpoint` defines the Webhook endpoint to which the data should be sent to.
|
||||
The result will contain an ID of the provider that we need in the next step.
|
||||
|
||||
You can configure multiple Email providers at the same time.
|
||||
To use the HTTP provider you need to [activate the Email provider](/apis/resources/admin/admin-service-activate-email-provider):
|
||||
|
||||
```bash
|
||||
curl -L 'https://$CUSTOM-DOMAIN/admin/v1/email/:id/_activate' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'Authorization: Bearer <TOKEN>' \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
The `id` is the provider's ID from the previous step.
|
||||
|
||||
See full API reference for [Email Providers](/apis/resources/admin/admin-service-list-email-providers) for more details.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### HTTP provider payload
|
||||
|
||||
In case of the Twilio and Email providers, the messages will be sent as before, in case of the HTTP providers the content of the messages is the same but as a HTTP call.
|
||||
|
||||
Here an example of the body of an payload sent via Email HTTP provider:
|
||||
|
||||
```json
|
||||
{
|
||||
"contextInfo": {
|
||||
"eventType": "user.human.initialization.code.added",
|
||||
"provider": {
|
||||
"id": "285181292935381355",
|
||||
"description": "test"
|
||||
},
|
||||
"recipientEmailAddress": "example@zitadel.com"
|
||||
},
|
||||
"templateData": {
|
||||
"title": "Zitadel - Initialize User",
|
||||
"preHeader": "Initialize User",
|
||||
"subject": "Initialize User",
|
||||
"greeting": "Hello GivenName FamilyName,",
|
||||
"text": "This user was created in Zitadel. Use the username Username to login. Please click the button below to finish the initialization process. (Code 0M53RF) If you didn't ask for this mail, please ignore it.",
|
||||
"url": "http://example.zitadel.com/ui/login/user/init?authRequestID=\u0026code=0M53RF\u0026loginname=Username\u0026orgID=275353657317327214\u0026passwordset=false\u0026userID=285181014567813483",
|
||||
"buttonText": "Finish initialization",
|
||||
"primaryColor": "#5469d4",
|
||||
"backgroundColor": "#fafafa",
|
||||
"fontColor": "#000000",
|
||||
"fontFamily": "-apple-system, BlinkMacSystemFont, Segoe UI, Lato, Arial, Helvetica, sans-serif",
|
||||
"footerText": "InitCode.Footer"
|
||||
},
|
||||
"args": {
|
||||
"changeDate": "2024-09-16T10:58:50.73237+02:00",
|
||||
"code": "0M53RF",
|
||||
"creationDate": "2024-09-16T10:58:50.73237+02:00",
|
||||
"displayName": "GivenName FamilyName",
|
||||
"firstName": "GivenName",
|
||||
"lastEmail": "example@zitadel.com",
|
||||
"lastName": "FamilyName",
|
||||
"lastPhone": "+41791234567",
|
||||
"loginNames": [
|
||||
"Username"
|
||||
],
|
||||
"nickName": "",
|
||||
"preferredLoginName": "Username",
|
||||
"userName": "Username",
|
||||
"verifiedEmail": "example@zitadel.com",
|
||||
"verifiedPhone": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
There are 3 elements to this message:
|
||||
|
||||
- `contextInfo`, with information on why this message is sent like the Event, which Email or SMS provider is used and which recipient should receive this message
|
||||
- `templateData`, with all texts and format information which can be used with a template to produce the desired message
|
||||
- `args`, with the information provided to the user which can be used in the message to customize
|
||||
@ -1,74 +0,0 @@
|
||||
---
|
||||
title: SMS, SMTP and HTTP Provider for Notifications
|
||||
---
|
||||
|
||||
All Notifications send as SMS and Email are customizable as that you can define your own providers,
|
||||
which then send the notifications out. These providers can also be defined as an HTTP type,
|
||||
and the text and content, which is used to send the SMS's and Emails will get send to a Webhook as JSON.
|
||||
|
||||
With this everything can be customized or even custom logic can be implemented to use a not yet supported provider by ZITADEL.
|
||||
|
||||
## How it works
|
||||
|
||||
There is a default provider configured in ZITADEL Cloud, both for SMS's and Emails, but this default providers can be changed through the respective API's.
|
||||
|
||||
This API's are provided on an instance level:
|
||||
- [SMS Providers](/apis/resources/admin/sms-provider)
|
||||
- [Email Providers](/apis/resources/admin/email-provider)
|
||||
|
||||
To use a non-default provider just add, and then activate. There can only be 1 provider be activated at the same time.
|
||||
|
||||
## Resulting messages
|
||||
|
||||
In case of the Twilio and SMTP providers, the messages will be sent as before, in case of the HTTP providers the content of the messages is the same but as a HTTP call.
|
||||
|
||||
Here an example of the body of an Email sent via HTTP provider:
|
||||
```json
|
||||
{
|
||||
"contextInfo": {
|
||||
"eventType": "user.human.initialization.code.added",
|
||||
"provider": {
|
||||
"id": "285181292935381355",
|
||||
"description": "test"
|
||||
},
|
||||
"recipientEmailAddress": "example@zitadel.com"
|
||||
},
|
||||
"templateData": {
|
||||
"title": "Zitadel - Initialize User",
|
||||
"preHeader": "Initialize User",
|
||||
"subject": "Initialize User",
|
||||
"greeting": "Hello GivenName FamilyName,",
|
||||
"text": "This user was created in Zitadel. Use the username Username to login. Please click the button below to finish the initialization process. (Code 0M53RF) If you didn't ask for this mail, please ignore it.",
|
||||
"url": "http://example.zitadel.com/ui/login/user/init?authRequestID=\u0026code=0M53RF\u0026loginname=Username\u0026orgID=275353657317327214\u0026passwordset=false\u0026userID=285181014567813483",
|
||||
"buttonText": "Finish initialization",
|
||||
"primaryColor": "#5469d4",
|
||||
"backgroundColor": "#fafafa",
|
||||
"fontColor": "#000000",
|
||||
"fontFamily": "-apple-system, BlinkMacSystemFont, Segoe UI, Lato, Arial, Helvetica, sans-serif",
|
||||
"footerText": "InitCode.Footer"
|
||||
},
|
||||
"args": {
|
||||
"changeDate": "2024-09-16T10:58:50.73237+02:00",
|
||||
"code": "0M53RF",
|
||||
"creationDate": "2024-09-16T10:58:50.73237+02:00",
|
||||
"displayName": "GivenName FamilyName",
|
||||
"firstName": "GivenName",
|
||||
"lastEmail": "example@zitadel.com",
|
||||
"lastName": "FamilyName",
|
||||
"lastPhone": "+41791234567",
|
||||
"loginNames": [
|
||||
"Username"
|
||||
],
|
||||
"nickName": "",
|
||||
"preferredLoginName": "Username",
|
||||
"userName": "Username",
|
||||
"verifiedEmail": "example@zitadel.com",
|
||||
"verifiedPhone": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
There are 3 elements to this message:
|
||||
- contextInfo, with information on why this message is sent like the Event, which Email or SMS provider is used and which recipient should receive this message
|
||||
- templateData, with all texts and format information which can be used with a template to produce the desired message
|
||||
- args, with the information provided to the user which can be used in the message to customize
|
||||
@ -187,7 +187,7 @@ module.exports = {
|
||||
selector: "div#",
|
||||
},
|
||||
prism: {
|
||||
additionalLanguages: ["csharp", "dart", "groovy", "regex", "java", "php", "python", "protobuf"],
|
||||
additionalLanguages: ["csharp", "dart", "groovy", "regex", "java", "php", "python", "protobuf", "json", "bash"],
|
||||
},
|
||||
colorMode: {
|
||||
defaultMode: "dark",
|
||||
|
||||
@ -154,11 +154,10 @@ module.exports = {
|
||||
type: "category",
|
||||
label: "Customize",
|
||||
items: [
|
||||
"guides/manage/customize/branding",
|
||||
"guides/manage/customize/texts",
|
||||
"guides/manage/customize/behavior",
|
||||
"guides/manage/customize/restrictions",
|
||||
"guides/manage/customize/notifications",
|
||||
{
|
||||
type: "autogenerated",
|
||||
dirName: "guides/manage/customize",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user