> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.pro/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Delivery Failed Webhook

>  

Triggered when an email cannot be delivered due to repeated failures.

This is a permanent failure (hard bounce). No more delivery attempts will be made. Common causes include:
- Invalid email address
- Recipient's domain doesn't exist
- Recipient's mail server permanently rejects the email

**When it's sent**: After all retry attempts have been exhausted.




## OpenAPI

````yaml webhooks.yaml webhook message.failed
openapi: 3.1.0
info:
  title: AhaSend Webhooks
  description: >
    AhaSend webhook events documentation. This specification describes all
    webhook events that AhaSend sends to your configured webhook URLs.


    ## Overview


    Webhooks are HTTP callbacks that AhaSend sends to your configured URLs when
    specific events occur. They provide real-time notifications about:


    - **Message Events**: Email delivery status (sent, delivered, bounced,
    opened, etc.)

    - **Suppression Events**: When email addresses are automatically suppressed

    - **Domain Events**: DNS configuration issues

    - **Route Events**: Inbound email processing


    ## Standard Webhooks Compatibility


    AhaSend webhook deliveries use the Standard Webhooks header names,
    signed-content format, HMAC-SHA256 algorithm, and signature format. Secret
    handling is intentionally different from the encoded-secret convention
    assumed by some Standard Webhooks libraries, so compatibility with stock
    libraries is not unconditional.


    ### Security Headers


    All webhooks include these security headers for verification:


    - `webhook-id`: Unique identifier for the webhook event (used as idempotency
    key)

    - `webhook-timestamp`: Unix timestamp when the webhook was sent

    - `webhook-signature`: HMAC-SHA256 signature of the payload using the
    resource secret


    ### Verification


    The HMAC key is the literal UTF-8 bytes of the `secret` returned when the
    webhook or route resource is created. Use the complete returned string,
    including any prefix. Do not Base64-decode it and do not strip a prefix.


    Use the AhaSend SDK verifier, or a verifier that explicitly accepts raw key
    bytes. A stock Standard Webhooks library is compatible only if it has a
    raw-secret/raw-key mode that preserves these literal UTF-8 bytes.
    Constructors that decode an encoded Standard Webhooks secret will derive a
    different key and reject valid AhaSend deliveries.


    The signed content is the unmodified `webhook-id`, `webhook-timestamp`, and
    raw request body joined with periods. See the [Standard Webhooks
    verification
    algorithm](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#verifying-webhook-authenticity)
    for the shared protocol details, subject to the AhaSend secret-handling
    boundary above.


    ### Retry Policy


    - Failed webhooks are retried **6 times** over **16+ minutes**

    - Only HTTP status codes **200-299** are considered successful

    - After **100 consecutive failures**, the webhook is automatically disabled

    - You'll receive an email notification when a webhook is disabled


    ### Payload Format


    All webhooks follow the Standard Webhooks payload structure:


    ```json

    {
      "type": "event.type",
      "timestamp": "2024-05-06T09:49:16.687031577Z",
      "data": {
        // Event-specific data
      }
    }

    ```


    ## Getting Started


    1. **Configure a webhook** in your AhaSend dashboard

    2. **Choose which events** you want to receive

    3. **Verify webhook signatures** using the literal resource secret as
    described above

    4. **Handle the events** in your application


    For more information, visit the [AhaSend webhook
    documentation](https://ahasend.pro/help/integrations/webhooks).
  version: 2.0.0
  contact:
    email: support@ahasend.pro
  license:
    name: Proprietary
servers:
  - url: https://your-webhook-endpoint.com
    description: Your webhook endpoint URL (configured in AhaSend dashboard)
security: []
tags:
  - name: Message Events
    description: >
      Webhooks for outbound email delivery tracking.


      These events track the lifecycle of emails you send through AhaSend, from
      initial reception through final delivery or failure.
  - name: Suppression Events
    description: >
      Webhooks for email suppression list changes.


      These events notify you when email addresses are automatically added to
      your suppression list due to delivery issues.
  - name: Domain Events
    description: >
      Webhooks for domain configuration issues.


      These events alert you to DNS configuration problems that could prevent
      email delivery.
  - name: Route Events
    description: >
      Webhooks for inbound email processing.


      These events deliver inbound emails to your application for processing
      (e.g., support tickets, replies).
paths: {}

````