> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Testing

> Test and debug webhooks locally with the CLI

# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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 test@yourdomain.com \
  --to test@example.com \
  --subject "Test Email" \
  --text "Testing webhook integration" \
  --sandbox
```

### SSL Certificate Verification

```bash theme={null}
# Skip SSL certificate verification for local endpoints
ahasend webhooks listen \
  --forward-to https://localhost:3000/webhook \
  --skip-verify
```

## Debugging

### Output Options

```bash theme={null}
# 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

* [Learn about webhooks](/cli/commands/webhooks)
* [Configure routes for inbound email](/cli/commands/routes)