Skip to main content
TypeScript

Authorizations

​
Authorization
string
header
required

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.

Query Parameters

​
integration_name
enum<string>

Only return subscriptions to this 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.

Available options:
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
Example:

"message.created"

​
is_subscribed
string

Filter by delivery status: true/1/yes returns only active subscriptions, false/0/no returns only paused ones (case-insensitive). Omit to return both.

Example:

"true"

​
integration_id
string

Only return the subscription rows sharing this integration_id — i.e. the rows created together by one POST /webhooks call

Example:

"00000000-0000-0000-0000-000000000000"

​
hook_url
string

Only return subscriptions delivering to this exact endpoint URL

Example:

"https://example.com/webhooks/periskope"

Response

Webhook subscriptions matching the filters, newest first

​
id
string

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
string

Id of the workspace (org) the webhook belongs to

Example:

"00000000-0000-0000-0000-000000000000"

​
hook_url
string

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
enum<string>

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.

Available options:
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
Example:

"ticket.created"

​
integration_type
string

Label of the integration that created the subscription. Webhooks created via this API default to 'webhook'.

Example:

"webhook"

​
type
enum<string>

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.

Available options:
zapier,
pabbly,
api,
webhook,
hubspot,
freshdesk,
slack,
jira,
salesforce,
zohodesk,
gsheets,
zohocrm
Example:

"webhook"

​
is_subscribed
boolean

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
string

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
object

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:
​
phone_scopes
string[]

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:
​
subscribed_at
string

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"