Create webhook endpoint

Request

Create a new webhook endpoint to receive real-time email event notifications.

Signature verification: Every webhook created through this API receives an opaque signing secret in the create response. MailerLogic computes a lowercase hexadecimal HMAC-SHA256 over the exact UTF-8 request body bytes and sends it in X-Webhook-Signature. Do not parse and re-serialize the JSON before verification. Capture the raw request body, compute the HMAC with the saved secret, and compare the two values using a constant-time comparison.

Delivery requests also include:

X-Webhook-ID: webhook endpoint UUID
X-MailerLogic-Event-ID: stable event UUID for idempotent processing
X-Webhook-Timestamp: event timestamp copied from the JSON payload
X-Event-Type: event name such as email.delivered

Webhook delivery is at least once. Deduplicate retries using the JSON event_id or matching X-MailerLogic-Event-ID value.

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):

{
  "url": "https://api.example.com/webhook",
  "events": ["email.delivered", "email.bounced"],
  "domain_ids": null
}

Domain group webhook (multiple domains):

{
  "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):

{
  "url": "https://support.example.com/webhook",
  "events": ["email.delivered"],
  "domain_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Security

ApiKeyAuth

Bodyapplication/jsonrequired

namestring

Optional webhook identifier

Example:"Production Webhook"

urlstring, (uri)required

HTTPS URL for webhook delivery

Example:"https://api.example.com/webhooks/email-events"

descriptionstring

Optional notes about this webhook

Example:"Main production webhook for email events"

domain_idsArray of strings or null, (uuid)

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

eventsArray of stringsrequired

Event types to receive

Items Enum:"email.sent""email.delivered""email.opened""email.clicked""email.bounced""email.complained""email.unsubscribed""email.failed""contact.created""contact.updated"

Example:

[
  "email.delivered",
  "email.opened",
  "email.clicked",
  "email.bounced"
]

is_activeboolean

Enable/disable webhook

Default:true

domain_idstring or null, (uuid)deprecated

DEPRECATED: Use domain_ids array instead. For backward compatibility, this is converted to domain_ids: [domain_id].

Example:"550e8400-e29b-41d4-a716-446655440000"

curl -i -X POST \
  https://api.mailerlogic.net/api/v1/customer/webhooks \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "name": "Production Webhook",
    "url": "https://api.example.com/webhooks/email-events",
    "description": "Main production webhook for email events",
    "domain_ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002"
    ],
    "domain_id": "550e8400-e29b-41d4-a716-446655440000",
    "events": [
      "email.delivered",
      "email.opened",
      "email.clicked",
      "email.bounced"
    ],
    "is_active": true
  }'

Responses

Webhook created successfully.

⚠️ IMPORTANT: The response includes a secret field inside the webhook object. This is the ONLY time you'll see it - save it immediately!

Bodyapplication/json

dataobject(WebhookEndpointWithSecret)

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!

webhookobject(WebhookEndpointWithSecret)

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!

messagestring

Example:"Webhook created successfully"

Response

{
  "webhook": {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Webhook",
    "url": "https://api.example.com/webhooks/email-events",
    "description": "Main production webhook",
    "domain_ids": [ … ],
    "domains": [ … ],
    "events": [ … ],
    "is_active": true,
    "secret": "8f2b5d8c8f4544e4b11682a4d7e0f681ab12cd34ef56ab78cd90ef12ab34cd56",
    "signing_secret": "8f2b5d8c8f4544e4b11682a4d7e0f681ab12cd34ef56ab78cd90ef12ab34cd56",
    "last_triggered_at": null,
    "last_status": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": "Webhook created successfully"
}