Webhooks provide real-time notifications about events in your AhaSend account. When an email is delivered, bounced, opened, or when other important events occur, AhaSend sends HTTP requests to your configured webhook URLs, enabling you to automate responses and keep your systems synchronized.
Real-Time Integration: Unlike polling APIs that require you to repeatedly check for updates, webhooks deliver event data instantly as it happens, making your applications more responsive and efficient.

​
What are Webhooks?

Webhooks are user-defined HTTP callbacks triggered by specific events in AhaSend. When an event occurs—such as an email being delivered or bouncing—AhaSend automatically sends a POST request to your webhook URL with detailed event data. This enables you to:

Automate Workflows

Trigger actions in your application when emails are delivered or bounce

Monitor Performance

Track email engagement in real-time without manual checking

Update User Interfaces

Show delivery status updates to users immediately

Handle Errors

Respond to delivery failures or suppression events automatically

​
How Webhooks Work in AhaSend

Event Occurs

An event happens in your account (email delivered, bounced, opened, etc.)

Webhook Triggered

AhaSend identifies any webhooks configured for that event type

HTTP Request Sent

AhaSend sends a POST request to your webhook URL with event data

Your Application Responds

Your endpoint processes the event and returns a 2xx status code
Delivery Guarantee: AhaSend retries failed webhook deliveries up to 6 times over 16+ minutes. Only HTTP status codes 200-299 are considered successful.

​
Available Webhook Events

AhaSend supports webhooks for various event types. You can choose which events to receive when configuring your webhook:

​
Understanding Message Lifecycle

The message lifecycle helps you understand when different webhook events occur:

​
Successful Delivery Path

Reception → Delivered → [Opened] → [Clicked]
  1. Reception: Email accepted and queued for delivery
  2. Delivered: Successfully sent to recipient’s mail server
  3. Opened: Recipient opens email (requires tracking enabled)
  4. Clicked: Recipient clicks tracked links (requires tracking enabled)

​
Bounce Scenarios

​
Creating Webhooks

Screenshot of the webhooks dashboard
Configure webhooks in your AhaSend dashboard to start receiving event notifications:

Access Webhooks Dashboard

  1. Log in to your AhaSend Dashboard
  2. Navigate to the Webhooks section from the main menu
  3. Click the “Add Webhook” button

Configure Webhook URL

Enter Your Endpoint URL:
  • Provide the complete URL where you want to receive webhook events
  • Must be a valid HTTPS URL (HTTP allowed for development)
  • Should respond with 2xx status codes for successful processing
Example URLs:
https://api.yourapp.com/webhooks/ahasend
https://yourapp.com/api/email-events

Select Events

Choose which events to receive:Option 1: All Events
  • Select “Send all events to this endpoint URL”
  • Simplest option, receives every event type
  • Good for comprehensive logging or analytics
Option 2: Specific Events
  • Select “I’ll choose which events to send”
  • Pick individual event types you need
  • More efficient for targeted use cases

Create and Verify

  1. Click “Create Webhook” to save your configuration
  2. Note the Webhook Secret displayed on the details page
  3. Copy and store the secret securely for signature verification

​
Testing Your Webhooks

Verify your webhook integration works correctly before going live:

Use Test Events

  1. Go to your webhook details page in the dashboard
  2. Click “Send Test Event”
  3. Select which event types to test
  4. Click “Send Test Events”
Test events arrive within seconds and contain realistic sample data.

Development Tools

For Quick Testing:
  • Use Beeceptor to create temporary webhook URLs
  • Inspect incoming requests and verify payload structure
  • Test without writing code first
For Development:
  • Use ngrok to expose local development servers
  • Test webhook handling in your actual application code

Verify Response Handling

Ensure your endpoint:
  • Returns 2xx status codes for successful processing
  • Processes requests quickly (under 10 seconds)
  • Handles duplicate events gracefully using webhook-id
  • Validates webhook signatures for security
Timeout Considerations: Webhook requests timeout after 10 seconds. Perform heavy processing asynchronously.

​
Security and Verification

AhaSend follows the Standard Webhooks specification for secure webhook delivery:

​
Security Headers

Every webhook request includes security headers: 
webhook-id: wh_1234567890abcdef
webhook-timestamp: 1683360000
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

​
Signature Verification

Use Standard Webhooks libraries for easy verification: 
import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.WEBHOOK_SECRET, { format: 'raw' });

// In your webhook handler
export async function handleWebhook(request) {
  const payload = await request.text();
  const headers = {
    'webhook-id': request.headers.get('webhook-id'),
    'webhook-timestamp': request.headers.get('webhook-timestamp'),
    'webhook-signature': request.headers.get('webhook-signature')
  };

  try {
    const event = webhook.verify(payload, headers);
    // Process verified event
    console.log('Event:', event.type, event.data);
    return new Response('OK', { status: 200 });
  } catch (error) {
    return new Response('Invalid signature', { status: 400 });
  }
}
Standard Webhooks Libraries: AhaSend webhooks are fully compatible with Standard Webhooks libraries available for Python, JavaScript, Go, PHP, Ruby, Java, Rust, C#, and Elixir.

​
Webhook Payload Structure

Complete Payload Documentation: For detailed event schemas and all payload fields, see the Webhook Events API Reference.
All AhaSend webhooks follow the Standard Webhooks payload format: 
{
  "type": "event.type",
  "timestamp": "2024-05-06T09:49:16.687031577Z",
  "data": {
    // Event-specific data
  }
}

​
Message Event Example

{
  "type": "message.delivered",
  "timestamp": "2024-05-06T09:50:16.687031577Z",
  "data": {
    "account_id": "4cdd7bdd-294e-4762-892f-83d40abf5a87",
    "event": "on_delivered",
    "from": "[email protected]",
    "recipient": "[email protected]",
    "subject": "Welcome to our service",
    "message_id_header": "message-id-12345",
    "id": "ahasend-message-67890"
  }
}

​
Suppression Event Example

{
  "type": "suppression.created",
  "timestamp": "2024-05-06T12:57:06.451529527Z",
  "data": {
    "account_id": "4cdd7bdd-294e-4762-892f-83d40abf5a87",
    "recipient": "[email protected]",
    "created_at": "2024-05-06T12:57:06.451529617Z",
    "expires_at": "2024-06-05T12:57:06.451529617Z",
    "reason": "Too many hard bounces",
    "sending_domain": "yourcompany.com"
  }
}

​
Best Practices

​
Troubleshooting

​
Advanced Integration Patterns

Event-Driven Architecture

Use webhooks to trigger microservices, update user interfaces, and orchestrate complex workflows based on email events.

Real-Time Analytics

Stream webhook events to analytics platforms for real-time email performance dashboards and reporting.

Customer Support Integration

Automatically create support tickets from bounce events and delivery failures to keep your team informed.

Marketing Automation

Trigger marketing campaigns, update customer segments, and personalize user experiences based on email engagement.

Webhook API Reference

Complete API documentation for webhook management

Security Guide

Detailed security implementation and best practices

Retry Policy

Understanding webhook delivery and retry behavior