Understanding Webhook event payloads

Events triggered by webhooks contain payloads that describe and detail the events.

Find below a detailed description of the fields in a Webhook event payload.

Webhook event typeLink to this anchor

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.

Webhook event statusLink to this anchor

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 configured URL received the notification.
• 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.

Examples of payload by event typeLink to this anchor

Webhooks may trigger different types of events. These types have varying payload fields.

email_queuedLink to this anchor

{
  "id": UUID,
  "type": "email_queued",
  "organization_id": UUID,
  "project_id": UUID,
  "domain_id": UUID,
  "domain_name": string,
  "created_at": time,
  "email_queued_at": timed,
  "email_id": UUID,
  "email_from": string,
  "email_to": string,
  "email_headers": [
    {
      "key": string,
      "value": string
    }
  ]
}

email_droppedLink to this anchor

{
  {
  "id": UUID,
  "type": "email_dropped",
  "organization_id": UUID,
  "project_id": UUID,
  "domain_id": UUID,
  "domain_name": string,
  "created_at": time,
  "email_sent_at": time,
  "email_id": UUID,
  "email_from": string,
  "email_to": string,
  "email_headers": [
    {
      "key": string,
      "value": string
    }
  ],
  "email_sent_at": time,
  "email_error": string,
  "email_response_code": int,
  "email_response_message": string

email_deliveredLink to this anchor

{
  "id": UUID,
  "type": "email_delivered",
  "organization_id": UUID,
  "project_id": UUID,
  "domain_id": UUID,
  "domain_name": string,
  "created_at": time,
  "email_sent_at": time,
  "email_id": UUID,
  "email_from": string,
  "email_to": string,
  "email_headers": [
    {
      "key": string,
      "value": string
    }
  ],
  "email_response_code": int,
  "email_response_message": string
}

email_mailbox_not_foundLink to this anchor

{
  "id": UUID,
  "type": "email_mailbox_not_found",
  "organization_id": UUID,
  "project_id": UUID,
  "domain_id": UUID,
  "domain_name": string,
  "created_at": time,
  "email_sent_at": time,
  "email_id": UUID,
  "email_from": string,
  "email_to": string,
  "email_headers": [
    {
      "key": string,
      "value": string
    }
  ],
  "email_response_code": int,
  "email_response_message": string
}

email_spamLink to this anchor

{
  "id": UUID,
  "type": "email_spam",
  "organization_id": UUID,
  "project_id": UUID,
  "domain_id": UUID,
  "domain_name": string,
  "created_at": time,
  "email_sent_at": time,
  "email_id": UUID,
  "email_from": string,
  "email_to": string,
  "email_headers": [
    {
      "key": string,
      "value": string
    }
  ],
  "email_response_code": int,
  "email_response_message": string
}

email_deferredLink to this anchor

{
  "id": UUID,
  "type": "email_deferred",
  "organization_id": UUID,
  "project_id": UUID,
  "domain_id": UUID,
  "domain_name": string,
  "created_at": time,
  "email_sent_at": time,
  "email_id": UUID,
  "email_from": string,
  "email_to": string,
  "email_headers": [
    {
      "key": string,
      "value": string
    }
  ],
  "email_error": string,
  "email_next_try": time,
  "email_try_count": int,
  "email_response_code": int,
  "email_response_message": string
}