Skip to content

fix(tem): unify webhook xps #5051

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

Merged
merged 2 commits into from
Jun 3, 2025
Merged

fix(tem): unify webhook xps #5051

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9f7ac6b
fix(tem): unify webhook xps
ldecarvalho-doc Jun 2, 2025
75fb3ae
fix(tem): review jessi
ldecarvalho-doc Jun 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
2 changes: 1 addition & 1 deletion ...mber2024/2024-11-05-transactional-email-changed-webhook-event-update-to-ema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,5 @@ category: managed-services
product: transactional-email
---

The `email_error` field has been replaced by two new fields: `response_code` and `response_message`. This change allows for more precise error identification and improved tracking of response details. See the [documentation](/transactional-email/api-cli/webhook-events-payloads/) for full details.
The `email_error` field has been replaced by two new fields: `response_code` and `response_message`. This change allows for more precise error identification and improved tracking of response details. See the [documentation](/transactional-email/reference-content/webhook-events-payloads) for full details.

16 changes: 16 additions & 0 deletions macros/tem/webhook-event-status.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
macro: webhook-event-status
---

The Webhook event status indicates the status of the webhook delivery.

These are the different event statuses:

- `unknown_status`: The status of the event is unknown by default. This status is used when the event status has not been specified.
- `sending`: The webhook event is being sent. This means that the notification is in transit to the configured URL.
- `sent`: The webhook event was successfully sent. This status indicates that the notification was received by the configured URL.
- `failed`: The webhook event could not be sent after multiple attempts. This status means there were repeated errors during the attempt to send the notification.

<Message type="note">
Refer to the [Transactional Email API documentation](https://www.scaleway.com/en/developers/api/transactional-email/) for more information about event statuses.
</Message>
21 changes: 21 additions & 0 deletions macros/tem/webhook-event-types.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
macro: webhook-event-types
---

The Webhook event type defines the type of event that triggered the webhook.

These are the different event types:

- `unknown_type`: The event type is unknown by default. This type is used when the event type has not been specified.
- `email_queued`: The email was received and is being prepared to be sent to the destination servers. This event indicates that the email sending process has started.
- `email_dropped`: The email was sent but was definitively rejected by the destination server, or hard-bounced. This can occur due to incorrect or non-existent email addresses.
- `email_deferred`: The email was sent but was temporarily rejected by the destination server, or soft-bounced. In this case, the sending of the email will be automatically retried. This event type can occur when the destination server is temporarily unavailable.
- `email_delivered`: The email was successfully sent and accepted by the destination server. This event confirms that the email has reached the recipient's inbox.
- `email_spam`: The email was identified as spam by Scaleway or the destination server. This event indicates that the email was classified as spam, either by an automated filter or by the recipient.
- `email_mailbox_not_found`: The email was definitively rejected with a "mailbox not found" error. This indicates that the recipient's email address does not exist or is no longer active.
- `email_blocklisted` - An email was blocked by an active blocklist.
- `blocklist_created` - A blocklist is created for an email address. Any new emails sent by the address will be blocked.

<Message type="note">
Refer to the [Transactional Email API documentation](https://www.scaleway.com/en/developers/api/transactional-email/) for more information about event types.
</Message>
8 changes: 4 additions & 4 deletions menu/navigation.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2942,10 +2942,6 @@
{
"label": "Setting up and using TEM webhooks with Topics and Events",
"slug": "use-webhooks-with-sns-topics"
},
{
"label": "Understanding Webhook event payloads",
"slug": "webhook-events-payloads"
}
],
"label": "API/CLI",
Expand Down Expand Up @@ -2976,6 +2972,10 @@
{
"label": "Understanding managed dedicated IPs",
"slug": "tem-dedicated-ip"
},
{
"label": "Understanding Webhook event payloads",
"slug": "webhook-events-payloads"
}
],
"label": "Additional Content",
Expand Down
31 changes: 2 additions & 29 deletions pages/transactional-email/concepts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,35 +208,8 @@ Two plans are available:

## Webhook Event Type

The Webhook event type defines the type of event that triggered the webhook.

These are the different event types:

- `unknown_type`: The event type is unknown by default. This type is used when the event type has not been specified.
- `email_queued`: The email was received and is being prepared to be sent to the destination servers. This event indicates that the email sending process has started.
- `email_dropped`: The email was sent but was definitively rejected by the destination server, or hard-bounced. This can occur due to incorrect or non-existent email addresses.
- `email_deferred`: The email was sent but was temporarily rejected by the destination server, or soft-bounced. In this case, the sending of the email will be automatically retried. This event type can occur when the destination server is temporarily unavailable.
- `email_delivered`: The email was successfully sent and accepted by the destination server. This event confirms that the email has reached the recipient's inbox.
- `email_spam`: The email was identified as spam by Scaleway or the destination server. This event indicates that the email was classified as spam, either by an automated filter or by the recipient.
- `email_mailbox_not_found`: The email was definitively rejected with a "mailbox not found" error. This indicates that the recipient's email address does not exist or is no longer active.
- `email_blocklisted` - An email was blocked by an active blocklist.
- `blocklist_created` - A blocklist is created for an email address. Any new emails sent by the address will be blocked.

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

## Webhook Event Status

The Webhook event status indicates the status of the webhook delivery.

These are the different event statuses:

- `unknown_status`: The status of the event is unknown by default. This status is used when the event status has not been specified.
- `sending`: The webhook event is being sent. This means that the notification is in transit to the configured URL.
- `sent`: The webhook event was successfully sent. This status indicates that the notification was received by the configured URL.
- `failed`: The webhook event could not be sent after multiple attempts. This status means there were repeated errors during the attempt to send the notification.

<Message type="note">
Refer to the [Transactional Email API documentation](https://www.scaleway.com/en/developers/api/transactional-email/) for more information about event statuses.
</Message>
<Macro id="webhook-event-status" />
4 changes: 4 additions & 0 deletions pages/transactional-email/how-to/create-webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,10 @@ You can create only one webhook per domain.
</Message>
6. Click **Create Webhook** to confirm. A list of your webhooks appears.

<Message type="note">
Refer to the [Understanding webhook event payloads](/transactional-email/reference-content/webhook-events-payloads/) for more information on the content of webhook responses.
</Message>

## How to edit a webhook

Once you have created webhooks, you can edit their settings anytime.
Expand Down
10 changes: 9 additions & 1 deletion ...email/api-cli/webhook-events-payloads.mdx → ...rence-content/webhook-events-payloads.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Find below a detailed description of the fields in a [Webhook event](/transactio
| Tag | Description |
|---------|-------------------------------------|
| `id` | Event identifier |
| `type` | Event type |
| `type` | Event type. Find a full list of event types in the [section below](#webhook-event-type). |
| `organization_id` | Domain Organization |
| `project_id` | Domain Project |
| `domain_id` | Domain identifier |
Expand All @@ -40,6 +40,14 @@ Find below a detailed description of the fields in a [Webhook event](/transactio
| `email_response_message` | SMTP response message |


## Webhook event type

<Macro id="webhook-event-types" />

## Webhook event status

<Macro id="webhook-event-status" />

## Examples of payload by event type

Webhooks may trigger different [types of events](/transactional-email/concepts/#webhook-event-type). These types have varying payload fields.
Expand Down
Loading