Test Webhooks Locally with the CLI

Receive AhaSend webhook events on localhost without a public URL: stream them with ahasend webhooks listen, forward them and trigger tests.

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

Before running the examples, log in with a full API key, use your verified sender domain, and replace YOUR_RESOURCE_ID with a resource UUID from your test account. Create any named template, recipient, attachment, or JSON files first. Shell examples use Bash; examples that read JSON with jq need jq installed. Sends use sandbox mode.

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

An existing webhook must be enabled to emit events. For a disabled test webhook, start its listener, then run ahasend webhooks update YOUR_RESOURCE_ID --enable in another terminal. Disable it again before stopping the listener. A listener without --webhook-id creates an enabled temporary webhook.

# Listen for all webhook events
ahasend webhooks listen

# Use existing webhook
ahasend webhooks listen --webhook-id YOUR_RESOURCE_ID

# 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 YOUR_RESOURCE_ID \
  --events "message.delivered"

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

# Trigger all available events
ahasend webhooks trigger YOUR_RESOURCE_ID \
  --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 [e-mail] \
  --to [e-mail] \
  --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 listener prints its signing secret when it starts. Store that secret in your local handler’s configuration; use the full string as the raw UTF-8 HMAC key. Do not base64-decode it. See signature verification. The command automatically generates a webhook secret using the Standard Webhooks headers and format, with the full secret as raw UTF-8 bytes

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

• Learn about webhooks
• Configure routes for inbound email

Related Guides

• Install the CLI, CLI authentication, Webhook setup.
• Event reference, Webhook CLI, Signature verification.
• Retry policy, CLI configuration and output, API authentication.
• Permission scopes, Domain setup, Sandbox behavior.
• Suppression durations.