> ## Documentation Index > Fetch the complete documentation index at: https://docs.isnap.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a webhook subscription > Changes the URL, the event filter, the line filter, the description or the active flag of a webhook subscription. * **Credential:** an account API key. A trial key returns `401 unauthorized`. * **Line-scoped keys:** the list of a [line-scoped key](/authentication#line-scoped-keys) is not applied here: the key changes any subscription of the account, and can set any line filter. * **`Idempotency-Key`:** not honored. See [Operations that honor the key](/idempotency#operations-that-honor-the-key). * **Events:** none. No event announces the change: see [What events do not announce](/webhooks/event-catalog#what-events-do-not-announce). * **Guide:** [Turning off and changing a subscription](/webhooks/delivery#turning-off-and-changing-a-subscription) explains the effect of each field. `active: true` turns on a subscription that you, or a `410` response, turned off. It does not end a [suspension](/webhooks/delivery#suspension). ## Errors | Status | `error.code` | When | | - | - | - | | 400 | `validation_failed` | `id` is not `wh_` followed by 25 letters or digits. The body holds none of `url`, `events`, `line_ids`, `description` and `active`. `url` is not a URL. `events` is empty, or holds a name that is not an event type. `active` is not a boolean. `description` is longer than 255 characters. An entry of `line_ids` does not have the form of a line id. | | 400 | `webhook_url_not_allowed` | The new `url` is refused, for the same reasons as on create: see [URL rules](/webhooks/overview#url-rules). | | 404 | `not_found` | Your account has no subscription with this id. | | 500 | `internal_error` | The new `url` is longer than 2,048 characters. Shorten it. | The errors that every operation shares are in [Errors](/errors-and-rate-limits#errors). ## OpenAPI ````yaml PATCH /v1/webhooks/{id} openapi: 3.0.0 info: title: iSnap API version: 2.45.0 description: >- The iSnap API sends and receives iMessage, RCS and SMS on real phone lines, manages those lines, and reports events through webhooks. Every message is sent to a real recipient, with an `isnap_live_` key and with an `isnap_test_` key alike. Retry a `429` after `Retry-After` seconds. Retry a `500` or a `503` up to 2 times, with exponential backoff. Do not retry any other `4xx`: fix the request. Retry a write only on an operation that honors `Idempotency-Key`, with the key of the first attempt. Responses carry personal data: handles, names and message text. servers: - url: https://api.isnap.ai security: - bearerAuth: [] paths: /v1/webhooks/{id}: patch: summary: Update a webhook subscription description: >- Changes any of `url`, `events`, `line_ids`, `description` and `active` on a webhook subscription; send at least one of them. Accepts an API key. `events` and `line_ids` replace the stored lists, and `line_ids: null` removes the line filter. A new `url` passes the same checks as on create and applies to every request not yet sent, pending retries included. A new filter applies to the events that occur after the call: deliveries already created are still sent. `active: false` stops new deliveries, and what occurs while the subscription is inactive is not delivered later; a delivery already created ends `failed` at its next attempt, without a request, and can be replayed. `active: true` turns back on a subscription that you turned off or that a `410` response turned off. It does not end a suspension: only a successful `webhook.test` request does. Keys other than these five are ignored. Updating a subscription sends no event. parameters: - schema: type: string pattern: ^wh_[0-9A-Za-z]{25}$ description: >- Id of the webhook subscription, as returned in `id` by `POST /v1/webhooks`: `wh_` followed by 25 letters or digits. example: wh_3Kp8Rn9Fh2Lm5Qx7Vw1Yz4Bc6 required: true description: >- Id of the webhook subscription, as returned in `id` by `POST /v1/webhooks`: `wh_` followed by 25 letters or digits. name: id in: path requestBody: content: application/json: schema: type: object properties: url: type: string format: uri description: >- New URL, at most 2,048 characters: a longer URL returns `500 internal_error`. It passes the same checks as on create, and applies to every request not yet sent, pending retries included. events: type: array items: $ref: '#/components/schemas/WebhookEventName' minItems: 1 description: >- New event filter. It replaces the stored list, and applies to the events that occur after the call. line_ids: type: array nullable: true items: type: string pattern: ^line_[0-9A-Za-z]{25}$ description: 'Id of a line: `line_` followed by 25 letters or digits.' description: >- New line filter. An array replaces the stored list. `null` removes the filter: the subscription then receives the events of every line. description: type: string nullable: true maxLength: 255 description: >- Free text for your own use, at most 255 characters. `null` clears it. active: type: boolean description: >- `false` stops new deliveries, and a delivery already created ends `failed` at its next attempt, without a request. `true` turns back on a subscription that you turned off, or that a `410` response turned off. It does not end a suspension. responses: '200': description: The webhook subscription after the change. content: application/json: schema: $ref: '#/components/schemas/WebhookV1Envelope' '400': description: >- Invalid request. `error.code` is `validation_failed` when a parameter, a header or the body does not match its schema: `error.issues` then lists each problem. It is `webhook_url_not_allowed` when the URL is refused: `error.issues[0].code` then gives the reason, which is `not_https` (the scheme is not `https://`), `ssrf_blocked` (the host is, or resolves to, a loopback, link-local, private, carrier-grade NAT, multicast or reserved address; every address the host resolves to is checked), `dns_failed` (the host does not resolve) or `invalid_url`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: No valid credential. `error.code` is `unauthorized`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- Not found. `error.code` is `not_found`: the account has no webhook subscription with this id. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: >- Too many requests. `error.code` is `rate_limit_exceeded` when more than 100 requests came from the same network address in 60 seconds, whatever their API key or account: wait `error.retry_after` seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: >- Unexpected failure. `error.code` is `internal_error`. An operation that takes a JSON body also returns it when the body, sent as `application/json`, is not valid JSON. Quote `trace_id` when you report it to iSnap. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - bearerAuth: [] components: schemas: WebhookEventName: type: string enum: - message.queued - message.sent - message.delivered - message.read - message.failed - message.received - message.scheduled - message.cancelled - message.fallback_triggered - reaction.added - reaction.received - reaction.removed - line.connected - line.disconnected - line.offline - line.degraded - line.apple_id_flagged - line.quota_warning - line.quota_exceeded - line.capability_changed - line.terminated - line.variant_changed - line.variant_scheduled - line.variant_unscheduled - typing_indicator.started - typing_indicator.stopped - trial.linked - trial.dormant - trial.reactivated - trial.bind_conflict - trial.revoked - binding.released - pre_order.fulfilled - pre_order.cancelled - macos_session.rented - macos_session.released - webhook.test - '*' - message.* - reaction.* - line.* - typing_indicator.* - trial.* - binding.* - pre_order.* - macos_session.* - webhook.* description: >- An exact event type such as `message.received`, a family wildcard such as `line.*`, or `*` for every event. A wildcard for a family that does not exist is accepted and matches nothing. `webhook.test` is never delivered through an event filter: iSnap sends it only to a suspended webhook subscription, to check whether its URL responds again. WebhookV1Envelope: type: object properties: success: type: boolean enum: - true description: Always `true` on a success response. data: $ref: '#/components/schemas/WebhookV1' trace_id: type: string description: >- Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap. request_id: type: string description: >- Id of the request that produced this response: `req_` followed by 25 letters or digits. required: - success - data - trace_id - request_id ErrorEnvelope: type: object properties: success: type: boolean enum: - false description: Always `false` on an error response. data: nullable: true description: Always `null` on an error response. error: type: object properties: status: type: integer description: The HTTP status of the response. code: type: string description: >- Stable machine-readable code that names the refusal. Branch on this value. message: type: string description: >- Text for a person. It can change between versions: do not branch on it. retry_after: type: integer nullable: true description: >- Seconds to wait before the next attempt. Set on the `429` responses that know a delay, where the `Retry-After` header carries the same value. When it is above 60 seconds, do not wait in a request: schedule the call, or report the time. `null` on every other error. retry_at: type: string nullable: true description: >- ISO 8601 timestamp at which the refusal ends. Set only on `429 rebind_cap_reached`. `null` on every other error. issues: type: array nullable: true items: type: object properties: path: type: array items: anyOf: - type: string - type: number description: >- Where the problem is: the field names and array indexes that lead to it. message: type: string description: Text for a person. code: type: string description: >- Kind of problem. On `validation_failed`, for example `invalid_type`, `invalid_value`, `invalid_format`, `invalid_union`, `invalid_key`, `invalid_element`, `too_small`, `too_big`, `not_multiple_of`, `unrecognized_keys` or `custom`. The list is open: read `path` and `message`. min: type: integer description: >- Smallest accepted value. Present only on `limit_out_of_bounds`, `mac_quantity_not_a_pack`, `byop_reduction_strands_mac_sessions` and `byop_reduction_strands_byod_lines`. max: type: integer description: >- Largest accepted value. Present only on `limit_out_of_bounds` and `mac_sessions_exceed_byop_lines`, and on the `too_big` issue of an `Idempotency-Key` header longer than 255 characters. required: - path - message - code description: >- Problems found in the request, one entry each. Set on most `400 validation_failed` responses and on the refusals that name a field: a refused `handle` of `POST /v1/lookup` has `issues: null`. `null` on every other error. required: - status - code - message - retry_after - retry_at - issues description: >- What went wrong. The six fields are always present; `retry_after`, `retry_at` and `issues` are `null` when they do not apply. trace_id: type: string description: >- Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap. request_id: type: string description: >- Id of the request that produced this response: `req_` followed by 25 letters or digits. required: - success - data - error - trace_id - request_id description: The body of an error response. WebhookV1: type: object properties: id: type: string description: >- Id of the webhook subscription: `wh_` followed by 25 letters or digits. url: type: string description: URL that receives the deliveries. events: type: array items: type: string description: >- Event filter: exact event types, family wildcards such as `line.*`, or `*`. line_ids: type: array nullable: true items: type: string description: Line filter. `null` and an empty array both mean every line. description: type: string nullable: true description: >- Free text set with `PATCH /v1/webhooks/{id}`. `null` when none is set. active: type: boolean description: >- `false` when you turned the subscription off, or when the URL returned `410` to a delivery. A subscription that iSnap suspended stays `true`: no field reports a suspension. created_at: type: string description: Timestamp of creation, ISO 8601 in UTC. updated_at: type: string description: >- Timestamp of the last change made with `PATCH /v1/webhooks/{id}` or of the last rotation of the signing secret. secret: type: string description: >- Never present: the signing secret is returned only by `POST /v1/webhooks` and `POST /v1/webhooks/{id}/rotate-secret`. old_secret_expires_at: type: string nullable: true description: Never present. required: - id - url - events - line_ids - description - active - created_at - updated_at description: >- A webhook subscription, in the shape that `GET /v1/webhooks/{id}` and `PATCH /v1/webhooks/{id}` return. securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key created in the iSnap dashboard, or a trial key, sent as `Authorization: Bearer `. An API key starts with `isnap_live_` or `isnap_test_`; both act on the same account, lines and billing. A trial key acts on its trial only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.