# Create webhook endpoint

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"]
}

Endpoint: POST /api/v1/customer/webhooks
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `name` (string)
    Optional webhook identifier
    Example: "Production Webhook"

  - `url` (string, required)
    HTTPS URL for webhook delivery
    Example: "https://api.example.com/webhooks/email-events"

  - `description` (string)
    Optional notes about this webhook
    Example: "Main production webhook for email events"

  - `domain_ids` (array,null)
    Optional array of domain UUIDs to scope webhook to specific domains.
- If null or empty array: webhook receives events from ALL domains (customer-level)
- If array with 1 UUID: webhook receives events from ONE domain
- If array with multiple UUIDs: webhook receives events from those specific domains (domain group)

Use Case: If your plan has 20 domains but only 5 webhook endpoints, group related domains together.
    Example: ["550e8400-e29b-41d4-a716-446655440001","550e8400-e29b-41d4-a716-446655440002"]

  - `events` (array, required)
    Event types to receive
    Enum: "email.sent", "email.delivered", "email.opened", "email.clicked", "email.bounced", "email.complained", "email.unsubscribed", "email.failed"

  - `is_active` (boolean)
    Enable/disable webhook

  - `domain_id` (string,null)
    DEPRECATED: Use domain_ids array instead. For backward compatibility, this is converted to domain_ids: [domain_id].
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Response 201 fields (application/json):

  - `webhook` (object)
    Webhook endpoint response that includes the signing secret.
IMPORTANT: The secret is only returned when creating or regenerating.
Save it securely - you won't see it again!

  - `webhook.id` (string)
    Webhook endpoint ID

  - `webhook.customer_id` (string)
    Customer ID

  - `webhook.domain_ids` (array,null)
    Array of domain UUIDs this webhook receives events from.
- If null or empty: webhook is customer-level (receives events from ALL domains)
- If array with UUIDs: webhook receives events from those specific domains
    Example: ["550e8400-e29b-41d4-a716-446655440001","550e8400-e29b-41d4-a716-446655440002"]

  - `webhook.domains` (array)
    Array of domain objects with id and domain name
    Example: [{"id":"550e8400-e29b-41d4-a716-446655440001","domain":"marketing.example.com"},{"id":"550e8400-e29b-41d4-a716-446655440002","domain":"campaigns.example.com"}]

  - `webhook.domains.id` (string)

  - `webhook.domains.domain` (string)

  - `webhook.name` (string,null)
    Optional webhook identifier
    Example: "Production Webhook"

  - `webhook.url` (string)
    HTTPS URL for webhook delivery
    Example: "https://api.example.com/webhooks/email-events"

  - `webhook.description` (string,null)
    Optional notes about this webhook
    Example: "Main production webhook for email events"

  - `webhook.events` (array)
    Event types this webhook receives
    Enum: "email.sent", "email.delivered", "email.opened", "email.clicked", "email.bounced", "email.complained", "email.unsubscribed", "email.failed"

  - `webhook.is_active` (boolean)
    Whether webhook is enabled

  - `webhook.last_triggered_at` (string,null)
    Timestamp of last webhook delivery

  - `webhook.last_status` (integer,null)
    HTTP status code from last delivery
    Example: 200

  - `webhook.created_at` (string)
    When webhook was created

  - `webhook.updated_at` (string)
    When webhook was last updated

  - `webhook.secret` (string)
    HMAC-SHA256 signing secret for webhook signature verification.

CRITICAL: Save this immediately! It's only shown once.

Use this secret to verify webhook authenticity by computing:

signature = HMAC-SHA256(payload, secret)


Compare this with the X-Webhook-Signature header.
    Example: "whsec_8jKp3nXw7rQ9sL2mY4hT6vB1nC5xZ0aE7fG2hI9jK4lM6nO8pQ1rS3tU5vW7xY"

  - `message` (string)
    Example: "Webhook created successfully"

## Response 400 fields (application/json):

  - `error` (string)
    Error code or message

## Response 401 fields (application/json):

  - `error` (string)
    Error code or message

## Response 403 fields (application/json):

  - `error` (string)
    Example: "Webhook limit reached (3/3 used). Upgrade your plan or delete an existing webhook."