> ## 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.

# Webhooks

> Configure and test webhook endpoints for real-time events

# Webhooks Command

Manage webhook endpoints for receiving real-time email events.

## Overview

```bash theme={null}
ahasend webhooks [subcommand] [flags]
```

Available subcommands:

* `list` - List all webhooks
* `create` - Create a new webhook
* `get` - Get webhook details
* `update` - Update webhook configuration
* `delete` - Delete a webhook
* `listen` - Listen for webhook events (development)
* `trigger` - Trigger test events (development)

## List Webhooks

```bash theme={null}
ahasend webhooks list
```

## Create Webhook

```bash theme={null}
# Basic webhook
ahasend webhooks create \
  --url https://your-app.com/webhooks/ahasend \
  --events message.delivered,message.bounced

# With description
ahasend webhooks create \
  --url https://api.example.com/email-events \
  --events message.delivered,message.opened,message.clicked \
  --description "Production email event handler"

# All events
ahasend webhooks create \
  --url https://app.example.com/webhooks \
  --events all
```

### Available Events

| Event                     | Description                  |
| ------------------------- | ---------------------------- |
| `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             |
| `message.opened`          | Email opened by recipient    |
| `message.clicked`         | Link clicked in email        |
| `suppression.created`     | New suppression added        |
| `domain.dns_error`        | DNS resolution failure       |

## Get Webhook Details

```bash theme={null}
ahasend webhooks get webhook_1234567890abcdef
```

## Update Webhook

```bash theme={null}
# Update URL
ahasend webhooks update webhook_1234567890abcdef \
  --url https://new-api.example.com/webhooks

# Update events
ahasend webhooks update webhook_1234567890abcdef \
  --events message.delivered,message.opened,message.clicked

# Update both
ahasend webhooks update webhook_1234567890abcdef \
  --url https://api.example.com/v2/webhooks \
  --events all \
  --description "Updated webhook endpoint"
```

## Delete Webhook

```bash theme={null}
# With confirmation prompt
ahasend webhooks delete webhook_1234567890abcdef

# Skip confirmation
ahasend webhooks delete webhook_1234567890abcdef --force
```

## Listen for Events (Development)

Listen for webhook events in real-time using WebSocket connection. This command establishes a WebSocket connection to receive webhook events and can forward them to a local endpoint for development.

```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

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

### Listen Flags

| Flag            | Description                                            |
| --------------- | ------------------------------------------------------ |
| `--webhook-id`  | Use existing webhook instead of creating temporary one |
| `--forward-to`  | Local endpoint to forward events to                    |
| `--events`      | Filter specific events (client-side filtering)         |
| `--slim-output` | Slim down the payload for console output               |
| `--skip-verify` | Skip SSL certificate verification for local endpoints  |

<Note>
  The command automatically generates a webhook secret for signing forwarded events using the standard-webhooks specification. It also handles disconnections with buffered event replay.
</Note>

## Trigger Test Events (Development)

Manually trigger webhook events for 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 events
ahasend webhooks trigger webhook_1234567890abcdef \
  --all-events
```

<Note>
  The trigger command is only available in development environments for testing webhook integrations.
</Note>

## Next Steps

* [Configure routes for inbound email](/cli/commands/routes)
* [View statistics](/cli/commands/stats)