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

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

Event Simulation Scenarios

Integration Testing

Development Workflow

SSL Certificate Verification

Debugging

Output Options

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