Skip to main content

​
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 for all webhook events
ahasend webhooks listen

# Use existing webhook
ahasend webhooks listen --webhook-id abcd1234-5678-90ef-abcd-1234567890ab

# Forward events to local endpoint
ahasend webhooks listen --forward-to http://localhost:3000/webhook

# Filter specific event types
ahasend webhooks listen --events message.opened,message.clicked

# Slim output (only event types)
ahasend webhooks listen --slim-output

​
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. Start webhook listener with event forwarding
ahasend webhooks listen \
  --forward-to http://localhost:3000/api/webhooks/ahasend \
  --events message.delivered,message.bounced,message.failed

# 2. Or use an existing webhook
ahasend webhooks listen \
  --webhook-id your-webhook-id \
  --forward-to http://localhost:3000/api/webhooks/ahasend

# 3. Trigger test events (in another terminal)
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

​
SSL Certificate Verification

# Skip SSL certificate verification for local endpoints
ahasend webhooks listen \
  --forward-to https://localhost:3000/webhook \
  --skip-verify

​
Debugging

​
Output Options

# Show detailed request/response information
ahasend webhooks listen \
  --verbose \
  --debug

# Show only event types (slim output)
ahasend webhooks listen \
  --slim-output

# Filter specific events
ahasend webhooks listen \
  --events message.delivered,message.opened

​
Common Issues

Signature Verification Failed: The command automatically generates a webhook secret using the standard-webhooks specification Events Not Received: Check that the webhook URL is correct and the local server is running Connection Lost: The command handles disconnections with buffered event replay, automatically reconnecting when possible

​
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

⌘I