# Update webhook endpoint

`PUT /api/webhooks/{id}`

Updates any supplied endpoint fields: name, URL, description, status, and payload mapping. Newly accepted messages pin the endpoint destination and shaping revision. Pending deliveries keep those pinned revisions. Pausing an endpoint stops sends.

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.

## Parameters

### id

path parameter; required.

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

## 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
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused"
      ]
    },
    "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": []
}
```

Example:

```json
{
  "status": "paused"
}
```

## Responses

### 200

Success

Content type: `application/json`.

Schema:

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

### 400

Invalid request.

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

### 404

Resource not found in this account.

Content type: `application/json`.

Schema:

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

### 429



### 503



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