[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for YDB](../index.md) > [Tutorials](index.md) > Yandex Cloud Postbox integration with external systems via webhooks

# Integrating Yandex Cloud Postbox with external systems using webhooks


In this tutorial, you will set up streaming of [Yandex Cloud Postbox](../../postbox/index.md) events to [Yandex Data Streams](../../data-streams/index.md) and triggering [webhooks](https://en.wikipedia.org/wiki/Webhook) in external systems. To process and store data, you will use [Yandex Cloud Functions](../../functions/index.md) and [Yandex Managed Service for YDB](../index.md).

You can implement this solution using the Yandex Cloud [management console](https://console.yandex.cloud) even if you have no coding skills.

To set up event streaming and processing:

1. [Get your cloud ready](#before-begin).
1. [Create service accounts](#service-accounts).
1. [Create a static access key](#static-key).
1. [Create a Managed Service for YDB](#ydb).
1. [Create a data stream in Data Streams](#stream).
1. [Set up Yandex Cloud Postbox resources](#postbox).
1. [Set up Cloud Functions resources](#serverless-functions).
1. [Test the solution](#test-solution).

If you no longer need the resources you created, [delete them](#clear-out).


## Get your cloud ready {#before-begin}

Sign up for Yandex Cloud and create a [billing account](../../billing/concepts/billing-account.md):
1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account.
1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../billing/quickstart/index.md) and [link](../../billing/operations/pin-cloud.md) a cloud to it.

If you have an active billing account, you can create or select a [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud).

[Learn more about clouds and folders here](../../resource-manager/concepts/resources-hierarchy.md).


### Required paid resources {#paid-resources}

The infrastructure support cost includes:

* Fee for YDB operations and data storage (see [Yandex Managed Service for YDB pricing](../pricing/serverless.md)).
* Fee for Data Streams data storage (see [Yandex Data Streams pricing](../../data-streams/pricing.md)).
* Fee for function invocation count, computing resources allocated for the function, and outgoing traffic (see [Cloud Functions pricing](../../functions/pricing.md)).
* Fee for using Yandex Cloud Postbox (see [Yandex Cloud Postbox pricing](../../postbox/pricing.md)).


## Create service accounts {#service-accounts}

Create these two [service accounts](../../iam/concepts/users/service-accounts.md):

* `yds-functions` to call the [function](../../functions/concepts/function.md) in Cloud Functions and write events to [Data Streams](../../data-streams/concepts/glossary.md#stream-concepts).
* `postbox-user` to send emails via Yandex Cloud Postbox.

1. Create a service account named `yds-functions`:

    {% list tabs group=instructions %}

    - Management console {#console}

      1. In the [management console](https://console.yandex.cloud), select the [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) where you are going to create your infrastructure.
      1. Navigate to **Identity and Access Management** and click **Create service account**.
      1. In the **Name** field, enter `yds-functions` for name.
      1. Click ![image](../../_assets/console-icons/plus.svg) **Add role** and select the `yds.editor` and `functions.functionInvoker` [roles](../../iam/concepts/access-control/roles.md).
      1. Click **Create**.

    {% endlist %}

1. Similarly, create a service account named `postbox-user` and assign the `postbox.sender` [role](../../postbox/security/index.md#postbox-sender) to it.


## Create a static access key {#static-key}

Create a [static access key](../../iam/concepts/authorization/access-key.md) to use for sending emails:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
  1. Navigate to **Identity and Access Management** and select `postbox-user` from the list of service accounts. In the window that opens:

      1. In the top panel, click ![plus](../../_assets/console-icons/plus.svg) **Create new key** and select **Create static access key**.
      1. Click **Create**.
      1. Save the ID and the secret key.

          {% note alert %}

          After you close this dialog, the key value will no longer be available.

          {% endnote %}

{% endlist %}


## Create a Managed Service for YDB database {#ydb}

To create a data stream for Yandex Cloud Postbox events, you need a Managed Service for YDB database. Create a [serverless Managed Service for YDB database](../concepts/resources.md#serverless):

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
  1. Navigate to **Managed Service for YDB** and click **Create a database**.
  1. In the **Name** field, specify `postbox-events-ydb`.
  1. In the **Database type** field, select `Serverless`.
  1. Do not edit the other database settings. Click **Create a database**.

  Wait for the database to start. While being created, your database will have the `Provisioning` status. Once it is ready for use, its status will change to `Running`.

{% endlist %}


## Create a data stream in Data Streams {#stream}

Create a [data stream](../../data-streams/concepts/glossary.md#stream-concepts) to log Yandex Cloud Postbox events:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
  1. Navigate to **Data Streams** and click **Create stream**.
  1. In the **Database** field, select the `postbox-events-ydb` database you created earlier.
  1. In the **Name** field, enter the stream name: `postbox-events-stream`.
  1. In the **Pricing Mode** field, select `Actual usage`.
  1. Do not edit the other data stream settings. Click **Create**.

{% endlist %}

Wait for the stream to start. Once the stream is ready for use, its status will change from `Creating` to `Active`.


## Set up Yandex Cloud Postbox resources {#postbox}

In Yandex Cloud Postbox, [configure](../../postbox/concepts/glossary.md#subscription) event logging to Data Streams, create a sender [address](../../postbox/concepts/glossary.md#adress), and [verify](../../postbox/operations/check-domain.md) your domain ownership.


### Create a Yandex Cloud Postbox configuration {#config}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
  1. Navigate to **Cloud Postbox**.
  1. In the left-hand panel, select ![image](../../_assets/console-icons/list-ul.svg) **Configurations** and click **Create configuration**.
  1. In the **Name** field, specify the configuration name: `postbox-events-config`.
  1. Under **Subscriptions**, click **Add** and fill out the form that opens:

      1. In the **Name** field, specify the [subscription](../../postbox/concepts/glossary.md#subscription) name: `postbox-events-subscribe`.
      1. In the **Data stream** field, select the [data stream](../../data-streams/concepts/glossary.md#stream-concepts) named `postbox-events-stream`.
      1. Toggle the **Enabled** option on to activate the subscription.

  1. Do not edit the other configuration settings. Click **Create configuration**.

{% endlist %}


### Create a Yandex Cloud Postbox address {#address}

1. Generate the `privatekey.pem` key to create a DKIM signature by running this command in the terminal:

    ```bash
    openssl genrsa -out privatekey.pem 2048
    ```

    {% note info %}

    `openssl` comes preinstalled in Linux and macOS. If using Windows, you need to install it manually. For more information, refer to the [project's website](https://openssl-library.org/).

    {% endnote %}

1. Create a Yandex Cloud Postbox address:

    {% list tabs group=instructions %}

    - Management console {#console}

      1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
      1. Navigate to **Cloud Postbox**.
      1. In the left-hand panel, select ![at](../../_assets/console-icons/at.svg) **Addresses** and click **Create address**.
      1. In the **Domain** field, specify the domain you will use to send emails. You can use a domain of any level, as long as you own it.
      1. In the **Selector** field, specify a selector, e.g., `postbox`. Make sure to only use this selector in the resource record you create when [verifying domain ownership](#domain).
      1. In the **Configuration** field, select `postbox-events-config` you previously created.
      1. In the **Private key** field, paste the contents of the `privatekey.pem` file from the previous step.
      1. Do not change the other address settings. Click **Create address**.
      1. Click the newly created address in the list that opens.
      1. Under **Signature verification** on the address info page, copy and save the [TXT record](../../dns/concepts/resource-record.md#txt) from the **Value** field.

    {% endlist %}


### Verify your domain ownership {#domain}

To send emails, confirm domain ownership. After creating an address, DKIM signature settings will be generated on its page. Specify them as the values of the resource records you need to add to your domain zone. You can add the records via your registrar or in [Yandex Cloud DNS](../../dns/index.md), if you have delegated your Yandex Cloud domain.

{% list tabs group=dkim %}

- Simple setup {#easy}

    With the simple setup, Yandex Cloud Postbox automatically generates DKIM keys. The two CNAME records you need to add to your DNS provider are displayed under **Email signature configuration (DKIM)** on the address page.

    **Example of creating resource records in Yandex Cloud DNS**

    1. In the [management console](https://console.yandex.cloud), select the folder containing the address and your domain zone.
    
       If you do not have a [public DNS zone](../../dns/concepts/dns-zone.md#public-zones) yet, [create](../../dns/operations/zone-create-public.md) one:
    1. Navigate to **Cloud Postbox**.
    1. Select the new address and open the **Email signature configuration (DKIM)** section.
    1. For each of the two CNAME records, complete the following steps:
    
        1. Navigate to **Cloud DNS**.
        1. Select your domain zone.
        1. Click **Create record**.
        1. In the **Type** field, select `CNAME`.
        1. Enter the record name from the **Email signature configuration (DKIM)** section on the address page into the **Name** field, omitting the domain.
    
           {% note info %}
    
           Other DNS services may require a full record name, including the domain.
    
           {% endnote %}
    
        1. In the **Data** field, paste the record value from the **Email signature configuration (DKIM)** section on the address page.
        1. In the **TTL (in seconds)** field, specify the record lifetime.
        1. Click **Create**.
    1. Navigate to **Cloud Postbox**.
    1. Select the address you created.
    1. Wait for Yandex Cloud Postbox to verify the DKIM signature settings. If the records are correct, the verification status on the address page will change to `Success`.

- Advanced setup {#advanced}

    With the advanced setup, you need to manually [generate the key](../../postbox/operations/create-address.md) for the DKIM signature. The **Email signature configuration (DKIM)** section on the address page displays a single TXT record you need to add to your DNS provider.

    **Example of creating resource records in Yandex Cloud DNS**
    
    1. In the [management console](https://console.yandex.cloud), select the folder containing the address and your domain zone.

        If you do not have a [public DNS zone](../../dns/concepts/dns-zone.md#public-zones) yet, [create](../../dns/operations/zone-create-public.md) one:
    1. Navigate to **Cloud DNS**.
    1. Select your domain zone.
    1. Click **Create record**.
    1. In the **Name** field, specify the name portion generated when creating the address, omitting the domain in `<selector>._domainkey` format, e.g., `postbox._domainkey`.

        {% note info %}

        For other DNS services, you may need to copy the entire record. The final record must look like this: `<selector>._domainkey.<domain>.`, e.g., `postbox._domainkey.example.com.`.

        {% endnote %}

    1. In the **Type** field, select `TXT`.
    1. Paste the contents of the **Value** field under **Email signature configuration (DKIM)** into the **Data** field. Note that the record value must be enclosed in quotes, such as follows:

        ```text
        "v=DKIM1;h=sha256;k=rsa;p=M1B...aCA8"
        ```

        {% note info %}

        Other DNS services may have different requirements for resource record formatting. For more information, refer to your DNS provider’s guides.

        {% endnote %}

    1. In the **TTL (in seconds)** field, specify the record lifetime.
    1. Click **Create**.
    1. Navigate to **Cloud Postbox**.
    1. Select the address you created.
    1. Wait for Yandex Cloud Postbox to verify the DKIM signature settings. If the record is correct, the verification status on the address page will change to `Success`.

{% endlist %}

DNS server responses are cached, so you may experience delays when updating the resource record. If the verification status does not change within 24 hours, click **Run verification**.


## Set up Cloud Functions resources {#serverless-functions}

Create a [function](../../functions/concepts/function.md) to send a webhook and a [trigger](../../functions/concepts/trigger/index.md) to call that function upon event logging to the data stream.


### Create a function {#function}

{% list tabs group=programming_language %}

- Python {#python}

  1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
  1. Navigate to **Cloud Functions**.
  1. Create a function:

      1. Click **Create function**.
      1. In the **Name** field, enter the function name: `postbox-webhook`.
      1. Click **Create**.
  1. Create a function version:

      1. In the **Editor** window that opens, select `Python 3.12`.
      1. Disable **Add files with code examples**.
      1. Click **Continue**.
      1. In the **Code source** field, select `Code editor`.
      1. Create the following two files:
      
          * `requirements.txt` containing a list of required dependencies:

              ```text
              requests
              ```
          * `index.py` containing the following function code:
  
              ```python
              import requests

              # URL of the webhook to call
              WEBHOOK_URL = "<webhook_URL>"


              def handler(event, context):
                  requests.post(WEBHOOK_URL, json=event)

                  return {
                      "statusCode": 200,
                  }
              ```
              
              Where `WEBHOOK_URL` is the URL of the webhook to send the request to.
      1. In the **Entry point** field, specify `index.handler`.
      1. Under **Parameters**, specify:

          * **Timeout**: `10 seconds`.
          * **Memory**: `128 MB`.

      1. Do not edit the other function version settings. Click **Save changes**.

- JavaScript {#node}

  1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
  1. Navigate to **Cloud Functions**.
  1. Create a function:

      1. Click **Create function**.
      1. In the **Name** field, enter the function name: `postbox-webhook`.
      1. Click **Create**.
  1. Create a function version:

      1. In the **Editor** window that opens, select `Node.js 18`.
      1. Disable **Add files with code examples**.
      1. Click **Continue**.
      1. In the **Code source** field, select `Code editor`.
      1. Create a file named `index.js` with the function code:

          ```js
          // URL of the webhook to call
          const WEBHOOK_URL = '<webhook_URL>'

          module.exports.handler = async function (event, context) {
              await fetch(WEBHOOK_URL, {
                  method: 'POST',
                  headers: {
                      'Content-Type': 'application/json',
                  },
                  body: JSON.stringify(event),
              });
 
              return {
                  statusCode: 200,
              };
          };
          ```

          Where `WEBHOOK_URL` is the URL of the webhook to send the request to.
      1. In the **Entry point** field, specify `index.handler`.
      1. Under **Parameters**, specify:

          * **Timeout**: `10 seconds`.
          * **Memory**: `128 MB`.

      1. Do not edit the other function version settings. Click **Save changes**.

{% endlist %}


### Create a trigger {#trigger}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
  1. Navigate to **Cloud Functions**.
  1. In the left-hand panel, select ![image](../../_assets/console-icons/gear-play.svg) **Triggers** and click **Create trigger**.
  1. In the **Name** field, enter the trigger name: `postbox-events-trigger`.
  1. In the **Type** field, select `Data Streams`.
  1. In the **Launched resource** field, select `Function`.
  1. Under **Data Streams settings**, select `postbox-events-stream` and the `yds-functions` service account.
  1. Under **Function settings**, select the `postbox-webhook` function and the `yds-functions` service account.
  1. Click **Create trigger**.

{% endlist %}


## Test the solution {#test-solution}

1. Use the Yandex Cloud Postbox address and static access key you created earlier to [send](../../postbox/operations/send-email.md#send-email) several test emails in any way you prefer.
1. Make sure the emails were delivered by checking the mailbox you sent them to.
1. Make sure the data about sent emails reaches the services:

    * Check the data stream:

        {% list tabs group=instructions %}

        - Management console {#console}

            1. In the [management console](https://console.yandex.cloud), select the folder where you are deploying your infrastructure.
            1. Navigate to **Data Streams**.
            1. Select the data stream named `postbox-events-stream`.
            1. Navigate to the ![text-align-justify](../../_assets/console-icons/text-align-justify.svg) **Data viewer** tab.
            
                The charts should show email sending events.

        {% endlist %}

    * View the [function logs](../../functions/operations/function/function-logs.md) and [trigger monitoring charts](../../functions/operations/trigger/trigger-monitoring.md).
    * Check that the webhooks for the sent email events were triggered in the external system.

After completing this tutorial, you will be able to trigger webhooks in external systems in response to Yandex Cloud Postbox email sending events.


## How to delete the resources you created {#clear-out}

To stop paying for the resources you created:

1. [Delete](../../functions/operations/trigger/trigger-delete.md) the trigger invoking the function in Cloud Functions.
1. [Delete](../../functions/operations/function/function-delete.md) the function in Cloud Functions.
1. [Delete](../../data-streams/operations/manage-streams.md#delete-data-stream) the stream in Data Streams.
1. [Delete](../operations/manage-databases.md#delete-db) the Managed Service for YDB database.
1. Delete the Yandex Cloud Postbox address and configuration.
1. Optionally, [delete](../../iam/operations/sa/delete.md) the service accounts.
1. Optionally, delete the [resource record](../../dns/operations/resource-record-delete.md) and [public DNS zone](../../dns/operations/zone-delete.md).