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();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"
}'{
"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"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "NOT_FOUND_ERROR",
"message": "No webhook subscription matches id",
"status": 404
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Update Webhook
Updates a webhook subscription row — at least one of hookUrl, integrationName, integrationMetadata, integrationType, isSubscribed or name.
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();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"
}'{
"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"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "NOT_FOUND_ERROR",
"message": "No webhook subscription matches id",
"status": 404
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Authorizations
Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.
Path Parameters
Id of the webhook subscription (UUID) — the id field of the rows returned when the webhook was created
1"00000000-0000-0000-0000-000000000000"
Body
New endpoint URL for this subscription. Must be a valid HTTP or HTTPS URL. Passing the current URL unchanged is a no-op.
"https://example.com/webhooks/periskope"
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.
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 "ticket.updated"
Keys merged into the existing integration_metadata (shallow merge — existing keys are kept unless overwritten here)
{ "description": "Webhook for ticket creation events" }
New integration_type label for the subscription. An empty string is ignored.
"webhook"
Set false to pause event delivery without deleting the subscription, true to resume it
true
New display name of the webhook, stored as integration_metadata.name
"Ticket webhook"
Response
The updated webhook subscription
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.
Unique id of the webhook subscription (UUID). Use it as the id path parameter when fetching, updating or deleting the subscription.
"00000000-0000-0000-0000-000000000000"
Id of the workspace (org) the webhook belongs to
"00000000-0000-0000-0000-000000000000"
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
"https://example.com/webhooks/periskope"
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.
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 "ticket.created"
Label of the integration that created the subscription. Webhooks created via this API default to 'webhook'.
"webhook"
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.
zapier, pabbly, api, webhook, hubspot, freshdesk, slack, jira, salesforce, zohodesk, gsheets, zohocrm "webhook"
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).
true
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.
"00000000-0000-0000-0000-000000000000"
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.
Show child attributes
Show child attributes
{ "id": "00000000-0000-0000-0000-000000000000", "name": "Ticket webhook" }
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.
["911111111111"]
When the subscription was created, as an ISO 8601 timestamp. Re-creating the same event type + hookUrl pair refreshes it.
"2026-01-15T09:30:00.000Z"
Was this page helpful?