# Create webhook endpoint

`POST /api/webhooks`

name is trimmed (1–80 characters). Description is at most 300 characters. Destinations require public HTTPS on port 443 and pass DNS/address checks. Save signingSecret now: it is returned once. Optional payloadMapping shapes the complete body. Omit it or use null for the standard body.

Send API requests to your Wildmail application origin. The documentation host does not serve API requests.

## Authentication

- apiKey: Send `Authorization: Bearer <token>` in the request headers. Wildmail scoped kmx_ API token.

- session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies.

Each bullet above is an alternative authentication method.

Required API key scope: `webhooks:write`.

Audience: management.

## Request body

Required.

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 300
    },
    "payloadMapping": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/PayloadMapping"
        },
        {
          "type": "null"
        }
      ],
      "description": "One optional mapping per endpoint. Null uses the standard webhook body. Mapping changes apply only to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body."
    }
  },
  "required": [
    "name",
    "url"
  ]
}
```

Example:

```json
{
  "name": "Order intake",
  "url": "https://api.example.com/email",
  "description": "Incoming purchase orders"
}
```

## Responses

### 201

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "endpoint": {
      "$ref": "#/components/schemas/Endpoint"
    },
    "signingSecret": {
      "type": "string"
    }
  },
  "required": [
    "endpoint",
    "signingSecret"
  ]
}
```

### 400

Invalid fields or unsafe destination.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 401

Missing, invalid or revoked credentials.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 403

Required scope or account access missing.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 429



### 500

Creation failed.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 503

Webhook secret encryption unavailable. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.

Headers:

```json
{
  "Cache-Control": {
    "description": "Request limiter responses use no-store.",
    "schema": {
      "type": "string"
    }
  }
}
```

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

## Referenced schemas

References resolve against the [OpenAPI specification](/openapi.json).

### #/components/schemas/PayloadMapping

```json
{
  "type": "object",
  "additionalProperties": false,
  "description": "Version 1 copies and reshapes fields from the standard wildmail.v1 event. Root output must be an object. Missing fields become null and missing arrays become []. Unmapped fields are omitted. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body. Maximum input size 64 KiB, 500 nodes, depth 12 including root, and 128 MiB output. No scripts, constants, fetching, or type conversion. Unsafe keys and pointer segments __proto__, prototype, constructor are rejected.",
  "properties": {
    "version": {
      "const": 1
    },
    "output": {
      "$ref": "#/components/schemas/PayloadObjectNode"
    }
  },
  "required": [
    "version",
    "output"
  ],
  "example": {
    "version": 1,
    "output": {
      "type": "object",
      "fields": {
        "title": {
          "type": "field",
          "path": "/subject"
        },
        "files": {
          "type": "array",
          "path": "/attachments",
          "items": {
            "type": "field",
            "path": "/filename"
          }
        }
      }
    }
  }
}
```

### #/components/schemas/Endpoint

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "failing"
      ]
    },
    "signingSecretHint": {
      "type": "string"
    },
    "secretReady": {
      "type": "boolean"
    },
    "subscribedEvents": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "lastDeliveryAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "payloadMapping": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/PayloadMapping"
        },
        {
          "type": "null"
        }
      ],
      "description": "Null uses the standard body. Mapping changes apply to newly accepted messages. Retries and replay preserve the mapping selected at acceptance and the request body."
    }
  },
  "required": [
    "id",
    "name",
    "url",
    "description",
    "status",
    "signingSecretHint",
    "secretReady",
    "subscribedEvents",
    "lastDeliveryAt",
    "payloadMapping"
  ]
}
```

### #/components/schemas/Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "error"
  ]
}
```

### #/components/schemas/PayloadObjectNode

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "const": "object"
    },
    "fields": {
      "type": "object",
      "propertyNames": {
        "minLength": 1,
        "maxLength": 128,
        "not": {
          "enum": [
            "__proto__",
            "prototype",
            "constructor"
          ]
        }
      },
      "additionalProperties": {
        "$ref": "#/components/schemas/PayloadMappingNode"
      }
    }
  },
  "required": [
    "type",
    "fields"
  ]
}
```

### #/components/schemas/PayloadMappingNode

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/PayloadFieldNode"
    },
    {
      "$ref": "#/components/schemas/PayloadObjectNode"
    },
    {
      "$ref": "#/components/schemas/PayloadArrayNode"
    }
  ]
}
```

### #/components/schemas/PayloadFieldNode

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "const": "field"
    },
    "path": {
      "type": "string",
      "maxLength": 1024,
      "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported."
    }
  },
  "required": [
    "type",
    "path"
  ]
}
```

### #/components/schemas/PayloadArrayNode

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "const": "array"
    },
    "path": {
      "type": "string",
      "maxLength": 1024,
      "description": "JSON Pointer into the current webhook catalog. Inside array items, relative to the current item. Empty string copies the item. Array indexes are not supported."
    },
    "items": {
      "$ref": "#/components/schemas/PayloadMappingNode"
    }
  },
  "required": [
    "type",
    "path",
    "items"
  ]
}
```
