AhaSend Webhooks

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",
      "webhook_id": "abe11757-2886-4b55-96f1-0e0afc95795a",
      "timestamp": "2024-05-06T09:49:16.687031577Z",
      "data": {
        // Event-specific data
      }
    }
    ```

    Message, suppression, and domain webhooks use `webhook_id`. Route
    webhooks use `route_id` instead.

    ## 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.com/help/integrations/webhooks).

  version: "2.0.0"
  contact:
    email: support@ahasend.com
  license:
    name: Proprietary

servers:


# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ahasend/refs/heads/main/asyncapi/ahasend-webhooks-openapi.yaml