Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: update webhooks guide, include new username events #116

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: update webhooks guide, include new username events #116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
301c20d
feat: include new webhook username events, update webhooks, custom em…
lfleischmann Jan 20, 2025
8507d98
fix: list all available types in email.send type property
lfleischmann Feb 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions _snippets/snippet-example.mdx
View file
Open in desktop

This file was deleted.

80 changes: 29 additions & 51 deletions guides/custom-emails/email-delivery.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ title: Send Custom Emails
description: Send emails with your own text and style.
---

import ProFeatureNote from '/snippets/pro-feature-note.mdx'

This guide will walk you through the process of sending your own emails instead of relying on Hanko's default email delivery.

## Create a Webhook
Expand All @@ -17,63 +19,39 @@ Create a webhook with the event `email.send`. This webhook will be triggered whe

## Disable Email delivery by Hanko

1. Log in to the [Hanko Cloud Console](https://cloud.hanko.io) and select your project.
2. Navigate to `Settings > Email`.
3. Disable the Email delivery by Hanko.
<ProFeatureNote/>

<Steps>
<Step title={"Access your project's email delivery settings"}>
Log in to Hanko Cloud, select your organization and project and navigate to `Settings > Email delivery`.
</Step>
<Step title={"Disable Email delivery"}>
Find the `Email delivery by Hanko` setting and click the toggle to disable it.
</Step>
</Steps>

Once disabled, Hanko will no longer send any emails on your behalf.

## Send your own emails

When an email needs to be sent, the `email.send` webhook event will be triggered, providing you with all the necessary data to send your own email. The webhook payload will include the following information:

```json
{
"subject": "",
"body_plain": "",
"body": "",
"to_email_address": "",
"delivered_by_hanko": true,
"accept_language": "",
"type": "passcode",
"data": {
"service_name": "",
"otp_code": "",
"ttl": 1000,
"valid_until": 1000
}
}
```

* `subject`: The subject line of the email.
* `body_plain`: The plain text version of the email body.
* `body`: The HTML version of the email body. (`nullable`)
* `to_email_address`: The recipient's email address.
* `delivered_by_hanko`: Indicates whether the email was delivered by Hanko (true) or not (false).
* `accept_language`: The preferred language for the email content.
* `type`: The type of the email being sent (e.g., "passcode").
* `data`: Additional data specific to the email type.

The `data` property in the webhook payload provides type-specific data that can be used to personalize the email further. The structure of the `data` property varies depending on the `type` of the email being sent.
When an email needs to be sent, the `email.send` webhook event will be triggered, providing you with all the necessary
data to send your own email. The webhook token payload will include the following information:

For example, if the email type is "passcode", the `data` property will include the following fields:
import WebhookEmailSendExample from '/snippets/webhooks/email-send-example.mdx';
import WebhookEmailSendProperties from '/snippets/webhooks/email-send-properties.mdx';

<Tabs>
<Tab title="passcode">
```json
"service_name": "",
"otp_code": "",
"ttl": 1000,
"valid_until": 1000
```
<AccordionGroup>
<Accordion title={"'email.send' token payload example"} defaultOpen={true}>
<WebhookEmailSendExample/>
</Accordion>
<Accordion title={"'email.send' token payload properties"}>
<WebhookEmailSendProperties/>
</Accordion>
</AccordionGroup>

|property|description|
|----|----|
|`service_name`|The name of the service set in the console as project name|
|`otp_code`|The passcode the user can use to log in|
|`ttl`|The validity duration of the passcode in seconds|
|`valid_until`|The Unix timestamp indicating when the passcode expires|
</Tab>
</Tabs>
The `data` property in the token payload provides type-specific data that can be used to personalize
the email further. The structure of the `data` property varies depending on the `type`
of the email being sent.

Using the provided webhook data, you can compose and send the email to the user using your preferred email service provider or custom email infra.
Using the provided webhook data, you can compose and send the email to the user using your preferred email service
provider or custom email infrastructure.
Loading