Setting up and using TEM webhooks with Topics and Events

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 to have real-time event alerts sent to your endpoints.

Before you start

To complete the actions presented below, you must have:

• A Scaleway account logged into the console
• Owner status or IAM permissions allowing you to perform actions in the intended Organization
• Configured your domain(s) with Transactional Email
• Added SPF, DKIM, MX and DMARC 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.

1. Create a Topics and Events 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. Make sure you enter the endpoint to which you would like to send your Webhooks.

   Tip

   If you do not yet have a webhook URL, you can use the tool webhook.site to generate one and receive your events on the interface.
   
   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.

   Open Image over content

   Close current Lightbox

4. Confirm your subscription.

   Tip

   If you are using webhook.site, you can refer to their interface to check the incoming requests and confirm the subscription.

5. Create a Transactional Email Webhook via the Scaleway API. Replace {{sns_arn_id}} with the ARN identifier you copied earlier.

   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}}"
   }'

   Tip

   In this example, we use email_delivered and email_dropped as the event types. Refer to the Transactional Email concepts page to get an extensive list of Transactional Email events.

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

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

Get a Webhook

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

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

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

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