---
title: Setting up and using TEM webhooks with Topics and Events
description: Learn to monitor and manage email activity in Scaleway Transactional Email.
tags: transactional webhooks sns managed-services
dates:
  validation: 2025-11-13
  posted: 2024-07-18
---
import Requirements from '@macros/iam/requirements.mdx'

import image from './assets/scaleway-webhook-site.webp'


A webhook is an automated message sent in real-time from one system to another when a specific event happens, the message is typically conveyed using HTTP requests that are sent to an endpoint of your choice.

You can set up webhooks for Scaleway Transactional Email and subscribe them to [Topics and Events topics](/topics-and-events/how-to/create-manage-topics/) to have real-time event alerts sent to your endpoints.

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- [Configured your domain(s) with Transactional Email](/transactional-email/how-to/configure-domain-with-transactional-email/)
- Added [SPF, DKIM](/transactional-email/how-to/authenticate-domain/#how-to-configure-spf-records), [MX](/transactional-email/how-to/authenticate-domain/#how-to-configure-mx-records) and [DMARC](/transactional-email/how-to/authenticate-domain/#how-to-configure-dmarc-records) records to your domain(s)
- Have the necessary quotas to use Transactional Email Webhooks during beta. You can request quotas from the [Scaleway betas page](https://www.scaleway.com/fr/betas/#email-webhooks).

1. [Create a Topics and Events topic](/topics-and-events/how-to/create-manage-topics/#how-to-create-a-topic) with Scaleway Topics and Events.

2. Copy the ARN identifier of the topic in the **Topics** tab as you will need it later.

3. [Create a subscription](/topics-and-events/how-to/create-manage-subscriptions/#how-to-create-a-subscription). Make sure you enter the endpoint to which you would like to send your Webhooks.

    <Message type="tip">
     If you do not yet have a webhook URL, you can use the tool [webhook.site](https://webhook.site/) to generate one and receive your events on the interface. <br /><br />
     When you access the website, a URL is generated automatically. You can copy it and add it as your endpoint when configuring your SNS subscription.
     <Lightbox image={image} alt="" />
    </Message>

4. [Confirm your subscription](/topics-and-events/how-to/create-manage-subscriptions/#how-to-confirm-an-http-or-https-subscription).

    <Message type="tip">
     If you are using [webhook.site](https://webhook.site/), you can refer to their interface to check the incoming requests and confirm the subscription.
    </Message>

5. Create a Transactional Email Webhook via the Scaleway API. Replace `{{sns_arn_id}}` with the ARN identifier you copied earlier.
    ```bash
    curl --request POST \
      --url https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/webhooks \
      --header 'X-Auth-Token: {{token}}' \
      --data '{
      "domain_id": "{{domain_id}}",
      "project_id": "{{project_id}}",
      "name": "My webhook name",
      "event_types": [
        "email_delivered",
        "email_dropped"
      ],
      "sns_arn": "{{sns_arn_id}}"
    }'
    ```

    <Message type="tip">
      In this example, we use `email_delivered` and `email_dropped` as the event types. Refer to the Transactional Email [concepts page](/transactional-email/concepts/#webhook-event-type) to get an extensive list of Transactional Email events.
    </Message>

Once your Webhook is created, you can try to send an email with your Transactional Email domain.

You should receive a response in your endpoint.

## Going further with Webhook API calls

You can perform other actions with Transactional Email Webhooks via the Scaleway API.

You will find examples of such calls below:

### List Webhooks

```bash
curl --request GET \
  --url https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/webhooks \
  --header 'X-Auth-Token: {{token}}'
```
### Get a Webhook

```bash
curl --request GET \
  --url https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/webhooks/{{webhook_id}} \
  --header 'X-Auth-Token: {{token}}'
```
### Update a Webhook

```bash
curl --request PATCH \
  --url https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/webhooks/{{webhook_id}} \
  --header 'X-Auth-Token: {{token}}'
  --data '{
  "name": "new name",
  "event_types": [
    "email_queued",
    "email_mailbox_not_found",
    "email_delivered",
    "email_dropped"
  ],
  "sns_arn": "{{sns_arn_id}}"
}'
```
### List Webhook events

```bash
curl --request GET \
  --url https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/webhooks/{{webhook_id}}/events \
  --header 'X-Auth-Token: {{token}}'
```

### Delete a Webhook

```bash
curl --request DELETE \
  --url https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/webhooks/{{webhook_id}} \
  --header 'X-Auth-Token: {{token}}'
```

<Message type="tip">
  Refer to the [Transactional Email API documentation](https://www.scaleway.com/en/developers/api/transactional-email/) for more information.
</Message>