Skip to main content
POST
Create webhook

Authorizations

x-api-key
string
header
required

API key (sk-proj-…) from Settings → API Keys. Required for sold API calls outside the Mermail console.

Headers

Idempotency-Key
string
required

Reuse only for the identical request after an uncertain response.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9._:-]+$

Path Parameters

workspaceId
string
required

Body

application/json
url
string<uri>
required

Public HTTPS destination. Credentials, fragments, private addresses and redirects are rejected. Write-only.

Maximum string length: 4096
eventTypes
enum<string>[]
required
Required array length: 1 - 5 elements
Available options:
message.received,
message.sent,
message.delivered,
message.bounced,
message.complained
allInboxes
boolean
required

Includes future inboxes. When false select mailboxIds explicitly.

mailboxIds
string[]
required
Maximum array length: 500
authorization
string | null
write-only

Optional Authorization header; null clears it. Never returned.

Maximum string length: 4096

Response

Result including signingSecret once. Save it securely; list/get never return it.

id
string
required
urlHost
string
required
eventTypes
enum<string>[]
required
Required array length: 1 - 5 elements
Available options:
message.received,
message.sent,
message.delivered,
message.bounced,
message.complained
allInboxes
boolean
required

Includes future inboxes. When false select mailboxIds explicitly.

mailboxIds
string[]
required
Maximum array length: 500
status
enum<string>
required
Available options:
active,
paused,
disabled,
deleted
hasAuthorization
boolean
required
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
signingSecret
string

Returned once on initial creation or rotation. Omitted on idempotent creation replay. Save securely.

Pattern: ^whsec_