---
title: "Update a webhook endpoint"
method: PATCH
path: "/v1/webhooks/{id}"
tags: ["Webhooks"]
---

# Update a webhook endpoint

`PATCH /v1/webhooks/{id}`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/webhooks/{id}`
- Auth: HTTP bearer

**Requires scope:** `manage`. Changes an endpoint's URL, event types, description or active state. An empty `event_types` list is refused with 422 `invalid_param_value`, as on create. An app connected by sign-in may change everything except `url` (403 `connected_app_not_allowed`).

## Path parameters

- `id` string, required

## Request body

- UpdateWebhookRequest
  - `url` string, uri: A new `https://` URL for the endpoint, checked as on create. The signing secret stays the same, and retries still due go to the new URL; left out, the URL is unchanged.
  - `event_types` string[]: Events to deliver, at least one. "*" is every event except thread.created, thread.updated, thread.deleted and message.delayed, sent only to an endpoint that names them.
  - `description` string: Replaces the endpoint's note, up to 255 characters; left out, it is unchanged. `null` is refused: clear it with an empty string, which is returned as it is.
  - `active` boolean: `false` pauses the endpoint: nothing is delivered to it, events raised meanwhile are not sent when it resumes, and a retry that comes due is dead-lettered. `true` resumes it; left out, it is unchanged.

## Response `200`

The updated endpoint.

- Webhook
  - `id` string, required: Webhook endpoint id (`whe_…`).
  - `url` string, uri, required: The URL events are POSTed to.
  - `event_types` string[], required: The event types this endpoint receives. `*` is every type except `thread.created`, `thread.updated`, `thread.deleted` and `message.delayed`, which reach an endpoint only when it lists them by name.
  - `description` string, nullable: Your note about the endpoint, or null when it has none.
  - `active` boolean, required: `false` while the endpoint is paused: nothing is delivered to it until `PATCH /v1/webhooks/{id}` sets it back to `true`.
  - `secret_rotated_at` string, date-time, nullable: When the signing secret was last rotated.
  - `previous_secret_expires_at` string, date-time, nullable: While set, deliveries are signed with both the new and the previous secret; null once the previous one stops signing.
  - `created_at` string, required: When the endpoint was created (ISO 8601, UTC).

## Other responses

- `400`: Invalid request — malformed JSON or a field failed validation. Also `feature_not_enabled` when this server has a feature switched off (custom domains before they are available).
- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `404`: Resource not found in this workspace, or the agent a send names is archived (`agent_archived`).
- `422`: Unprocessable — agent paused, recipient suppressed, a recipient at test.mails.ai other than reply@test.mails.ai (`unknown_test_address`), or abuse guard.
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)