> ## 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. # Create Webhook > Subscribes an endpoint URL to one or more event types — one subscription row per event type, sharing an integration_id. ## OpenAPI ````yaml api-reference/openapi-generated.json POST /v1/webhooks 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: post: tags: - Webhooks summary: Create a webhook description: >- Subscribes an endpoint URL to one or more event types — one subscription row per event type, sharing an integration_id. operationId: createWebhook requestBody: content: application/json: schema: type: object properties: hookUrl: type: string description: >- HTTP or HTTPS endpoint that will receive the subscribed events as JSON POST requests. Each delivery is signed with an HMAC-SHA256 signature of the body computed with the workspace signing key. example: https://example.com/webhooks/periskope integrationName: anyOf: - 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 - type: array items: 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: >- Event type(s) to subscribe the endpoint to — a single event type or an array. One subscription row is created per event type; the rows share the same hookUrl and integration_id. 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 - message.created integrationMetadata: type: object properties: {} description: >- Arbitrary JSON object stored with the subscription. Two keys are special: id (a non-empty string becomes the integration_id shared by the created rows; otherwise a UUID is generated) and name (used as the display name unless the name field is passed). example: name: Ticket webhook description: Webhook for ticket creation events integrationType: type: string description: >- Label stored as integration_type on the created rows. Defaults to 'webhook' — leave it unset unless an integration guide instructs otherwise. example: webhook type: type: string enum: - zapier - pabbly - api - webhook - hubspot - freshdesk - slack - jira - salesforce - zohodesk - gsheets - zohocrm description: >- Kind of integration record to create. Defaults to 'webhook'. Any other value makes the subscription invisible to this API — GET, PATCH and DELETE /webhooks/{id} and the list endpoint only address records of type 'webhook'. example: webhook name: type: string description: >- Display name of the webhook, stored as integration_metadata.name on every created row. Defaults to integrationMetadata.name, or to hookUrl when neither is given. example: Ticket webhook required: - hookUrl - integrationName responses: '201': description: >- The created subscription rows — one per event type in integrationName content: application/json: schema: type: array items: $ref: '#/components/schemas/Webhook' description: >- The created (or re-activated) subscription rows — one per event type in integrationName, all sharing the same hookUrl and integration_id 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 '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.createWebhook({ hookUrl: 'https://example.com/webhooks/periskope', integrationName: [ 'ticket.created', 'message.created', ], }); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X POST 'https://api.periskope.app/v1/webhooks' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "hookUrl": "https://example.com/webhooks/periskope", "integrationName": [ "ticket.created", "message.created" ] }' 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.