# Outbound Webhooks

MailerLogic sends real-time webhook notifications to your configured endpoint for all email events.

**Webhook Scopes:**

**Customer-Level Webhooks** (domain_ids = null or [])
- Receives events from ALL domains
- Simplest setup for single-backend applications

**Single Domain Webhooks** (domain_ids = [uuid])
- Receives events from ONE specific domain
- Useful for isolated domains

**Domain Group Webhooks** (domain_ids = [uuid1, uuid2, ...])
- Receives events from MULTIPLE specific domains
- Perfect for grouping related domains when webhook endpoint limits apply
- Example: Plan has 20 domains, 5 webhook limit → group marketing domains, support domains, etc.

**Mixed Approach**
- You can combine all three types
- Domain-specific/group webhooks fire first, then customer-level
- Maximize efficiency with limited webhook endpoints

**Create customer-level webhook (all domains):**
```bash
curl -X POST https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/mailerlogic",
    "events": ["email.delivered", "email.opened", "email.clicked", "email.bounced", "email.complained"],
    "name": "Production Webhook",
    "domain_ids": null,
    "is_active": true
  }'
```

**Create domain group webhook (multiple domains):**
```bash
curl -X POST https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://marketing.example.com/webhook",
    "events": ["email.opened", "email.clicked"],
    "name": "Marketing Domains Group",
    "domain_ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440003"
    ],
    "is_active": true
  }'
```

**Create single domain webhook:**
```bash
curl -X POST https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://support.example.com/webhook",
    "events": ["email.delivered", "email.bounced"],
    "name": "Support Domain Only",
    "domain_ids": ["550e8400-e29b-41d4-a716-446655440000"],
    "is_active": true
  }'
```

**All webhook events include:**
- `event` - Event type (e.g., "email.delivered", "email.opened")
- `timestamp` - ISO 8601 timestamp
- `email_id` - UUID of the email (except unsubscribe events)
- `tag` - Optional tag for filtering/grouping (if provided when sending)
- `metadata` - Optional custom metadata object (if provided when sending)

**Events sent to your endpoint:**



## List webhook endpoints

 - [GET /api/v1/customer/webhooks](https://developers.mailerlogic.com/customer-api.openapi/outbound-webhooks/paths/~1api~1v1~1customer~1webhooks/get.md): Retrieve all configured webhook endpoints for your account.

Tier Limits:
- Starter: 1 webhook endpoint
- Professional: 3 webhook endpoints
- Business: 10 webhook endpoints
- Custom: Configurable limit

## Create webhook endpoint

 - [POST /api/v1/customer/webhooks](https://developers.mailerlogic.com/customer-api.openapi/outbound-webhooks/paths/~1api~1v1~1customer~1webhooks/post.md): Create a new webhook endpoint to receive real-time email event notifications.

Webhook Scopes:
- Customer-Level (domain_ids = null/empty): Receives events from ALL domains
- Single Domain (domain_ids = [uuid]): Receives events from ONE domain
- Domain Group (domain_ids = [uuid1, uuid2, ...]): Receives events from MULTIPLE domains

Use Case - Plan Limits:
If your plan has 20 domains but only 5 webhook endpoints, group domains:
- Webhook 1: [marketing-domain, campaigns-domain, newsletters-domain] → marketing app
- Webhook 2: [support-domain, tickets-domain] → support app
- Webhook 3: [] (all remaining domains) → main backend

Event Types:
- email.sent - Email accepted for delivery
- email.delivered - Successfully delivered to recipient
- email.opened - Recipient opened the email
- email.clicked - Recipient clicked a link
- email.bounced - Email bounced
- email.complained - Spam complaint received
- email.unsubscribed - Recipient unsubscribed
- email.failed - Delivery failed

Examples:

Customer-level webhook (all domains):
json
{
  "url": "https://api.example.com/webhook",
  "events": ["email.delivered", "email.bounced"],
  "domain_ids": null
}


Domain group webhook (multiple domains):
json
{
  "url": "https://marketing.example.com/webhook",
  "events": ["email.opened", "email.clicked"],
  "domain_ids": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002",
    "550e8400-e29b-41d4-a716-446655440003"
  ]
}


Single domain webhook (backward compatible):
json
{
  "url": "https://support.example.com/webhook",
  "events": ["email.delivered"],
  "domain_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

## Update webhook endpoint

 - [PUT /api/v1/customer/webhooks/{webhookId}](https://developers.mailerlogic.com/customer-api.openapi/outbound-webhooks/paths/~1api~1v1~1customer~1webhooks~1%7Bwebhookid%7D/put.md): Update an existing webhook endpoint configuration.

You can change webhook scope by updating domain_ids:
- Set to null or []: Change to customer-level (all domains)
- Set to [uuid]: Change to single domain
- Set to [uuid1, uuid2, ...]: Change to domain group (multiple domains)

## Delete webhook endpoint

 - [DELETE /api/v1/customer/webhooks/{webhookId}](https://developers.mailerlogic.com/customer-api.openapi/outbound-webhooks/paths/~1api~1v1~1customer~1webhooks~1%7Bwebhookid%7D/delete.md): Remove a webhook endpoint from your account.

## Test webhook endpoint

 - [POST /api/v1/customer/webhooks/{webhookId}/test](https://developers.mailerlogic.com/customer-api.openapi/outbound-webhooks/paths/~1api~1v1~1customer~1webhooks~1%7Bwebhookid%7D~1test/post.md): Send a test event to verify webhook delivery.

Test Event Format:
json
{
  "event": "test",
  "timestamp": "2026-01-18T12:34:56Z",
  "customer_id": "uuid",
  "message": "Test webhook from MailerLogic"
}


The webhook will include an X-Webhook-Signature header for verification.

## Regenerate webhook secret

 - [POST /api/v1/customer/webhooks/{webhookId}/regenerate-secret](https://developers.mailerlogic.com/customer-api.openapi/outbound-webhooks/paths/~1api~1v1~1customer~1webhooks~1%7Bwebhookid%7D~1regenerate-secret/post.md): Generate a new HMAC-SHA256 secret for webhook signature verification.
The old secret will be immediately invalidated.