> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Update Webhook > Updates a webhook subscription row — at least one of hookUrl, integrationName, integrationMetadata, integrationType, isSubscribed or name. ## OpenAPI ````yaml api-reference/openapi-generated.json PATCH /v1/webhooks/{id} openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/webhooks/{id}: patch: tags: - Webhooks summary: Update a webhook description: >- Updates a webhook subscription row — at least one of hookUrl, integrationName, integrationMetadata, integrationType, isSubscribed or name. operationId: updateWebhook parameters: - schema: type: string minLength: 1 description: >- Id of the webhook subscription (UUID) — the id field of the rows returned when the webhook was created example: 00000000-0000-0000-0000-000000000000 required: true description: >- Id of the webhook subscription (UUID) — the id field of the rows returned when the webhook was created name: id in: path requestBody: content: application/json: schema: type: object properties: hookUrl: type: string description: >- New endpoint URL for this subscription. Must be a valid HTTP or HTTPS URL. Passing the current URL unchanged is a no-op. example: https://example.com/webhooks/periskope integrationName: type: string enum: - chat.created - chat.notification.created - message.created - message.updated - message.deleted - message.ack.updated - message.flagged - message.unflagged - reaction.created - ticket.created - ticket.updated - ticket.deleted - org.phone.connected - org.phone.disconnected - org.phone.updated - org.phone.qr - note.created - chat.custom_properties.updated - org.created - org.updated - org.member.created - org.member.updated - org.subscription.trial_will_end - org.integrations.updated - org.phone.created - chat.updated - chat.label.updated - reaction.updated - reaction.added - message.ticket.attached description: >- Move this subscription row to a different event type. Only this row is changed — other rows created in the same create call keep their event types. Deliverable event types: chat.created, chat.notification.created, message.created, message.updated, message.deleted, message.ack.updated, message.flagged, message.unflagged, reaction.created, ticket.created, ticket.updated, ticket.deleted, org.phone.connected, org.phone.disconnected, org.phone.updated, org.phone.qr, note.created, chat.custom_properties.updated. The legacy names org.created, org.updated, org.member.created, org.member.updated, org.subscription.trial_will_end, org.integrations.updated, org.phone.created, chat.updated, chat.label.updated, reaction.updated, reaction.added, message.ticket.attached are also accepted for compatibility, but events are never delivered for them. example: ticket.updated integrationMetadata: type: object properties: {} description: >- Keys merged into the existing integration_metadata (shallow merge — existing keys are kept unless overwritten here) example: description: Webhook for ticket creation events integrationType: type: string description: >- New integration_type label for the subscription. An empty string is ignored. example: webhook isSubscribed: type: boolean description: >- Set false to pause event delivery without deleting the subscription, true to resume it example: true name: type: string description: >- New display name of the webhook, stored as integration_metadata.name example: Ticket webhook responses: '200': description: The updated webhook subscription content: application/json: schema: $ref: '#/components/schemas/Webhook' examples: default: summary: Response body value: id: 00000000-0000-0000-0000-000000000000 org_id: 00000000-0000-0000-0000-000000000000 hook_url: https://example.com/webhooks/periskope integration_name: ticket.created integration_type: webhook type: webhook is_subscribed: true integration_id: 00000000-0000-0000-0000-000000000000 integration_metadata: id: 00000000-0000-0000-0000-000000000000 name: Ticket webhook phone_scopes: - '911111111111' subscribed_at: '2026-01-15T09:30:00.000Z' '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '404': description: No webhook subscription matches id content: application/json: examples: error: summary: No webhook subscription matches id value: code: NOT_FOUND_ERROR message: No webhook subscription matches id status: 404 schema: type: object properties: code: type: string example: NOT_FOUND_ERROR message: type: string example: No webhook subscription matches id status: type: integer example: 404 example: code: NOT_FOUND_ERROR message: No webhook subscription matches id status: 404 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', }); async function main() { const response = await client.webhooks.updateWebhook({ id: '00000000-0000-0000-0000-000000000000', hookUrl: 'https://example.com/webhooks/periskope', }); console.log(response); } main(); - lang: bash label: cURL source: >- curl -X PATCH 'https://api.periskope.app/v1/webhooks/00000000-0000-0000-0000-000000000000' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "hookUrl": "https://example.com/webhooks/periskope" }' components: schemas: Webhook: type: object properties: id: type: string description: >- Unique id of the webhook subscription (UUID). Use it as the id path parameter when fetching, updating or deleting the subscription. example: 00000000-0000-0000-0000-000000000000 org_id: type: string description: Id of the workspace (org) the webhook belongs to example: 00000000-0000-0000-0000-000000000000 hook_url: type: string description: >- HTTP(S) endpoint that receives the subscribed events as JSON POST requests, signed with an HMAC-SHA256 signature of the body computed with the workspace signing key example: https://example.com/webhooks/periskope integration_name: type: string enum: - chat.created - chat.notification.created - message.created - message.updated - message.deleted - message.ack.updated - message.flagged - message.unflagged - reaction.created - ticket.created - ticket.updated - ticket.deleted - org.phone.connected - org.phone.disconnected - org.phone.updated - org.phone.qr - note.created - chat.custom_properties.updated - org.created - org.updated - org.member.created - org.member.updated - org.subscription.trial_will_end - org.integrations.updated - org.phone.created - chat.updated - chat.label.updated - reaction.updated - reaction.added - message.ticket.attached description: >- The event type this subscription row delivers. One row exists per subscribed event type. Deliverable event types: chat.created, chat.notification.created, message.created, message.updated, message.deleted, message.ack.updated, message.flagged, message.unflagged, reaction.created, ticket.created, ticket.updated, ticket.deleted, org.phone.connected, org.phone.disconnected, org.phone.updated, org.phone.qr, note.created, chat.custom_properties.updated. The legacy names org.created, org.updated, org.member.created, org.member.updated, org.subscription.trial_will_end, org.integrations.updated, org.phone.created, chat.updated, chat.label.updated, reaction.updated, reaction.added, message.ticket.attached are also accepted for compatibility, but events are never delivered for them. example: ticket.created integration_type: type: string description: >- Label of the integration that created the subscription. Webhooks created via this API default to 'webhook'. example: webhook type: type: string enum: - zapier - pabbly - api - webhook - hubspot - freshdesk - slack - jira - salesforce - zohodesk - gsheets - zohocrm description: >- Kind of integration record. This API only lists, fetches, updates and deletes records of type 'webhook' — other values belong to built-in integrations (Zapier, Slack, ...) managed from the dashboard. example: webhook is_subscribed: type: boolean description: >- Whether event delivery is active. false pauses delivery without deleting the subscription — set it via PATCH isSubscribed, or automatically by Periskope when the endpoint keeps failing (workspace admins are emailed when that happens). example: true integration_id: type: string description: >- Groups the subscription rows created together: every row created by the same POST /webhooks call shares this id (taken from integrationMetadata.id when provided, otherwise generated). null on some legacy rows. example: 00000000-0000-0000-0000-000000000000 integration_metadata: type: object properties: id: type: string description: Mirrors integration_id example: 00000000-0000-0000-0000-000000000000 name: type: string description: Display name of the webhook example: Ticket webhook description: >- Metadata stored with the subscription. Webhooks created via this API always carry id (mirrors integration_id) and name (display name); any other keys sent in integrationMetadata are stored as-is. example: id: 00000000-0000-0000-0000-000000000000 name: Ticket webhook phone_scopes: type: array items: type: string description: >- Phone numbers whose events this webhook receives. Webhooks created via this API are unscoped (they receive events from every phone in the workspace); for unscoped rows this field is materialized in responses as the workspace's current full list of phone numbers. example: - '911111111111' subscribed_at: type: string description: >- When the subscription was created, as an ISO 8601 timestamp. Re-creating the same event type + hookUrl pair refreshes it. example: '2026-01-15T09:30:00.000Z' description: >- A webhook subscription — delivers one event type to one endpoint URL. Subscribing an endpoint to several event types creates one row per event type; the rows share an integration_id and can be paused (is_subscribed: false) or deleted individually. Only records of type 'webhook' are managed by this API. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.