Webhooks

Update a webhook endpoint

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

patch/v1/webhooks/{id}

Request

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

Path parameters

idstring required

Webhook endpoint id (whe_…).

Request body

urlstring 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_typesstring[]

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.

descriptionstring

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.

activeboolean

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

The updated endpoint.

idstring required

Webhook endpoint id (whe_…).

urlstring uri required

The URL events are POSTed to.

event_typesstring[] 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.

descriptionstring nullable

Your note about the endpoint, or null when it has none.

activeboolean required

false while the endpoint is paused: nothing is delivered to it until PATCH /v1/webhooks/{id} sets it back to true.

secret_rotated_atstring date-time nullable

When the signing secret was last rotated.

previous_secret_expires_atstring date-time nullable

While set, deliveries are signed with both the new and the previous secret; null once the previous one stops signing.

created_atstring required

When the endpoint was created (ISO 8601, UTC).

Changes

No recorded changes to this operation across all 1 revision of this API.