Update a webhook
const url = 'https://api.connect.ms/v2/webhooks/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"url":"example","description":"example","events":["example"],"apiVersion":"example","active":true,"autoDisableExempt":true,"autoDisableAfterMinutes":1,"atRiskAlertPercent":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://api.connect.ms/v2/webhooks/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "url": "example", "description": "example", "events": [ "example" ], "apiVersion": "example", "active": true, "autoDisableExempt": true, "autoDisableAfterMinutes": 1, "atRiskAlertPercent": 1 }'Changes the fields given and leaves the rest as they are. Setting apiVersion and events together on a legacy webhook converts it to v2 deliveries; a secret is issued and returned once if it had none.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The id of the webhook.
Header Parameters
Section titled “Header Parameters”The API version to use, for example 2026-10-01. Defaults to the version set on your API key.
A unique value of up to 255 characters, so a retried request is not acted on twice. Required for keys in Strict API Mode.
Request Bodyrequired
Section titled “Request Bodyrequired”The fields to change. Omitted fields are left as they are.
The fields to change. Omitted fields are left as they are.
object
A new URL to post deliveries to. An absolute http or https URL without embedded credentials.
A new description, up to 500 characters.
The event types to deliver, as dotted names such as sms.delivered; at least one. On a legacy webhook, send it together with apiVersion to convert it to v2 deliveries.
The Connect-Version the delivery bodies should follow. Setting it on a legacy webhook, together with events, converts it to v2 deliveries.
Turn deliveries on or off. Setting true also clears an automatic disable.
Never switch the webhook off automatically, however long it fails.
How many minutes of continuous failure before the webhook is switched off, between 5 and 10080 (7 days).
The percentage of the disable window after which to send one warning per outage, between 0 and 99. 0 means never and 1 means on the first failure.
Example generated
{ "url": "example", "description": "example", "events": [ "example" ], "apiVersion": "example", "active": true, "autoDisableExempt": true, "autoDisableAfterMinutes": 1, "atRiskAlertPercent": 1}Responses
Section titled “Responses”The updated webhook.
A webhook endpoint that receives event deliveries.
object
The unique id of the webhook.
The URL deliveries are posted to.
A description for your own reference, or null.
The event types delivered, as dotted names such as sms.delivered. A legacy webhook (apiVersion null) shows its legacy names instead.
The Connect-Version the delivery bodies follow. Null means the webhook still uses the legacy payload; set apiVersion and v2 event names together on update to convert it.
True while the webhook receives deliveries.
True when Connect switched the webhook off after it kept failing. Set active to true to turn it back on.
True when the webhook is never switched off automatically.
How many minutes of continuous failure switch the webhook off: its own setting, or the default when none is set.
The percentage of the disable window after which one warning is sent per outage. 0 means never and 1 means on the first failure; no warning is sent when autoDisableExempt is true.
When (UTC) the current run of failures began, or null when deliveries are succeeding.
How many delivery attempts in a row have failed. A 429 response from your endpoint is not counted.
The inbound number (E.164 format) this webhook is limited to, so it only receives sms.received for that number. Null means the whole workspace.
The version of the signing secret, used as the keyid of v2 delivery signatures. Goes up by one on each rotation.
The secret used to sign deliveries. Only returned by the response that issued it (create, rotate-secret, or an update that converts a legacy webhook); null everywhere else.
When (UTC) the webhook was created.
Example generated
{ "id": "example", "url": "example", "description": "example", "events": [ "example" ], "apiVersion": "example", "active": true, "autoDisabled": true, "autoDisableExempt": true, "autoDisableAfterMinutes": 1, "atRiskAlertPercent": 1, "failingSince": "2026-04-15T12:00:00Z", "consecutiveFailures": 1, "inboundNumber": "example", "secretVersion": 1, "secret": "example", "createdAt": "2026-04-15T12:00:00Z"}The request is not valid. The detail field says why, and errors lists any problems by field name.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The API key or bearer token is missing or not valid, or the request signature could not be verified.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The caller is not allowed to do this, or the workspace is not enabled for v2 webhooks.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}No webhook with that id.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}A request with this Idempotency-Key is still being processed. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}This Idempotency-Key was already used for a different request. Use a new key.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}This API key requires an Idempotency-Key header on every POST and PATCH.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The service is temporarily unavailable. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}