​
Webhook Testing

Test and debug webhook events locally without deploying to production using the AhaSend CLI.

​
Overview

The CLI provides tools for:
  • Creating local webhook listeners
  • Triggering test events
  • Forwarding events to local endpoints
  • Debugging webhook signatures and payloads

​
Local Webhook Listener

​
Basic Usage

# Listen on default port (8080)
ahasend webhooks listen http://localhost:8080/webhook

# Custom port with specific events
ahasend webhooks listen http://localhost:3000/events \
  --events "message.delivered,message.opened,message.clicked" \
  --port 3000

# Listen for all events
ahasend webhooks listen http://localhost:8080/webhook \
  --events "all" \
  --verbose

​
Available Events

  • message.reception - Email received by AhaSend
  • message.delivered - Email delivered to recipient
  • message.transient_error - Temporary delivery failure
  • message.failed - Permanent delivery failure
  • message.bounced - Email bounced
  • message.suppressed - Email suppressed
  • suppression.created - New suppression added
  • domain.dns_error - DNS resolution failure
  • message.opened - Email opened by recipient
  • message.clicked - Link clicked in email

​
Triggering Test Events

​
Development Testing

# Trigger single event
ahasend webhooks trigger webhook_1234567890abcdef \
  --events "message.delivered"

# Trigger multiple events
ahasend webhooks trigger webhook_1234567890abcdef \
  --events "message.delivered,message.opened,message.clicked"

# Trigger all available events
ahasend webhooks trigger webhook_1234567890abcdef \
  --all-events

​
Event Simulation Scenarios

# Test successful delivery flow
ahasend webhooks trigger webhook-id \
  --events "message.reception,message.delivered,message.opened,message.clicked"

# Test bounce handling
ahasend webhooks trigger webhook-id \
  --events "message.reception,message.bounced"

# Test error scenarios
ahasend webhooks trigger webhook-id \
  --events "message.transient_error,message.failed,domain.dns_error"

​
Integration Testing

​
Development Workflow

# 1. Create test webhook pointing to local server
ahasend webhooks create \
  --url http://localhost:3000/api/webhooks/ahasend \
  --events "message.delivered,message.bounced,message.failed" \
  --description "Local development webhook"

# 2. Start webhook listener to monitor events
ahasend webhooks listen http://localhost:3000/api/webhooks/ahasend \
  --verbose

# 3. Trigger test events
ahasend webhooks trigger webhook-id --all-events

# 4. Send test email to generate real events
ahasend messages send \
  --from [email protected] \
  --to [email protected] \
  --subject "Test Email" \
  --text "Testing webhook integration" \
  --sandbox

​
Custom Headers

# Add authentication headers
ahasend webhooks listen http://localhost:8080/webhook \
  --header "X-API-Key: secret123" \
  --header "Content-Type: application/json"

​
Debugging

​
Verbose Mode

# Show detailed request/response information
ahasend webhooks listen http://localhost:8080/webhook \
  --events "all" \
  --verbose \
  --debug

​
Common Issues

Signature Verification Failed: Ensure webhook secret is properly configured in your AhaSend account settings Events Not Received: Check that the webhook URL is correct and the local server is running Connection Refused: Verify the port is not already in use and firewall allows connections

​
Best Practices

  1. Start Simple: Test with single events before complex flows
  2. Use Sandbox Mode: Test with sandbox emails to avoid sending real messages
  3. Verify Signatures: Always validate webhook signatures in production
  4. Log Events: Keep detailed logs during development for debugging
  5. Test Error Cases: Simulate failures to ensure proper error handling

​
Next Steps