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

Before you startLink to this anchor

To complete the actions presented below, you must have:

• A Scaleway account logged into theconsole
• Owner status orIAM permissions allowing you to perform actions in the intended Organization
• Configured your domain(s) with Transactional Email
• AddedSPF, DKIM,MX andDMARC records to your domain(s)
• Have the necessary quotas to use Transactional Email Webhooks during beta. You can request quotas from theScaleway 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.siteto 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.

   

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 callsLink to this anchor

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

You will find examples of such calls below:

List WebhooksLink to this anchor

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

Get a WebhookLink to this anchor

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

Update a WebhookLink to this anchor

curl --request  \
  --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 eventsLink to this anchor

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 WebhookLink to this anchor

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