> ## Documentation Index > Fetch the complete documentation index at: https://help.kajabi.com/llms.txt > Use this file to discover all available pages before exploring further. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback: POST https://help.kajabi.com/feedback ```json { "path": "/api-reference/webhooks/create-hook", "feedback": "Description of the issue" } ``` Only submit feedback when you have something specific and actionable to report. # Create hook > Creates a new webhook subscription ## Request Body The request must include: * `data` - parent object which includes the children/nested attributes: * `target_url` - The URL where webhook events will be sent * `event` - The type of event to subscribe to (see available events below), for example "tag_added" * `resource_id` (optional) - Specific resource ID to filter events for, for example the id of the Contact Tag. When the property is omitted, the webhook will be triggered for all events of the specified type, as a wildcard webhook. ## Available Event Types | Event | Description | Required API Scopes | |-------|-------------|-------------------| | `purchase` | Customer makes a purchase | `view:purchases` | | `payment_succeeded` | Payment transaction completes successfully | `view:transactions` | | `order_created` | New order is created | `view:transactions`, `view:orders` | | `form_submission` | Someone submits a form | `view:form_submissions` | | `tag_added` | Tag is added to a contact | `view:contacts` | | `tag_removed` | Tag is removed from a contact | `view:contacts` | **Note**: You can only create webhooks for events you have permission to access based on your API key scopes. For example to use tags you need the `view:contacts` scope, which is included in the account owner api key scope. ## Sample Payloads You can view sample webhook payloads for each event type: * `GET /v1/hooks/purchase_sample` * `GET /v1/hooks/payment_succeeded_sample` * `GET /v1/hooks/order_created_sample` * `GET /v1/hooks/form_submission_sample` * `GET /v1/hooks/tag_added_sample` * `GET /v1/hooks/tag_removed_sample` Example request targeting a specific tag: ```json { "data": { "type": "hooks", "attributes": { "target_url": "https://example.com/webhook", "event": "tag_added", "resource_id": "123" }, "relationships": { "site": { "data": { "id": "456", "type": "sites" } } } } } ``` Example request using a wildcard webhook: ```json { "data": { "type": "hooks", "attributes": { "target_url": "https://example.com/webhook", "event": "tag_added" }, "relationships": { "site": { "data": { "id": "456", "type": "sites" } } } } } ``` ## Actual Payloads The actual payloads are sent to the `target_url` as a POST request with the following JSON body: ```json { "id": "hash_id", "event": "tag_added", "payload": [], } ``` The `id` is the ID of the resource that triggered the event. The `event` is the type of event that triggered the webhook. The `payload` is the actual payload of the event and the content will be similar to the sample payloads above. ## OpenAPI ````yaml /openapi.yaml post /v1/hooks openapi: 3.1.1 info: title: Kajabi API V1 version: 1.0.1 description: > ## Public API * Server URL `https://api.kajabi.com` * Endpoint paths are prefixed with `/v1` * Version endpoint `GET https://api.kajabi.com/v1/version` * See the [Developers Site](https://developers.kajabi.com) for documentation and examples. * Try the demo [Postman collection](https://www.postman.com/kajabi-apis/beta-public-api-demo/collection/fg4iyaz/kajabi-public-api-v1) ## API Keys * Your API `client_id` and `client_secret` are available on the [User API Keys](https://app.kajabi.com/admin/settings/security) section of the Kajabi Admin Portal. * Custom API Keys can be created with specific permissions. * Click the "Create User API Key" button, enter a name (e.g. "My project"), select the user and permissions, and click "Create". * For security purposes, you may "Delete" or "Rotate" the api credentials at any time; which will invalidate any access tokens granted with the credentials. ## Video Walkthroughs * [Capabilities](https://drive.google.com/file/d/1Puc9B2sSdA-RQb7YMxmUXg4FVoEXytoc/view?usp=sharing) * [Getting Started](https://drive.google.com/file/d/1hbGRShkxven_QMWvgYrerHKURbcZrnvJ/view?usp=sharing) * [Error Examples](https://drive.google.com/file/d/1i0wQK71I1jpaZVsxYwsn62gVj40S_E7Y/view?usp=sharing) * [External Contact Form](https://drive.google.com/file/d/1HqpULXvan5TOK3LvM7nILCuCkCaX0kFT/view?usp=sharing) contact: email: support@kajabi.com name: Support url: >- https://help.kajabi.com/hc/en-us/articles/4404549690523-How-to-Get-Help-From-Kajabi-Live-Agents license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.kajabi.com description: Production security: [] paths: /v1/hooks: post: tags: - Webhooks summary: Create hook description: > Creates a new webhook subscription ## Request Body The request must include: * `data` - parent object which includes the children/nested attributes: * `target_url` - The URL where webhook events will be sent * `event` - The type of event to subscribe to (see available events below), for example "tag_added" * `resource_id` (optional) - Specific resource ID to filter events for, for example the id of the Contact Tag. When the property is omitted, the webhook will be triggered for all events of the specified type, as a wildcard webhook. ## Available Event Types | Event | Description | Required API Scopes | |-------|-------------|-------------------| | `purchase` | Customer makes a purchase | `view:purchases` | | `payment_succeeded` | Payment transaction completes successfully | `view:transactions` | | `order_created` | New order is created | `view:transactions`, `view:orders` | | `form_submission` | Someone submits a form | `view:form_submissions` | | `tag_added` | Tag is added to a contact | `view:contacts` | | `tag_removed` | Tag is removed from a contact | `view:contacts` | **Note**: You can only create webhooks for events you have permission to access based on your API key scopes. For example to use tags you need the `view:contacts` scope, which is included in the account owner api key scope. ## Sample Payloads You can view sample webhook payloads for each event type: * `GET /v1/hooks/purchase_sample` * `GET /v1/hooks/payment_succeeded_sample` * `GET /v1/hooks/order_created_sample` * `GET /v1/hooks/form_submission_sample` * `GET /v1/hooks/tag_added_sample` * `GET /v1/hooks/tag_removed_sample` Example request targeting a specific tag: ```json { "data": { "type": "hooks", "attributes": { "target_url": "https://example.com/webhook", "event": "tag_added", "resource_id": "123" }, "relationships": { "site": { "data": { "id": "456", "type": "sites" } } } } } ``` Example request using a wildcard webhook: ```json { "data": { "type": "hooks", "attributes": { "target_url": "https://example.com/webhook", "event": "tag_added" }, "relationships": { "site": { "data": { "id": "456", "type": "sites" } } } } } ``` ## Actual Payloads The actual payloads are sent to the `target_url` as a POST request with the following JSON body: ```json { "id": "hash_id", "event": "tag_added", "payload": [], } ``` The `id` is the ID of the resource that triggered the event. The `event` is the type of event that triggered the webhook. The `payload` is the actual payload of the event and the content will be similar to the sample payloads above. parameters: [] requestBody: content: application/vnd.api+json: schema: type: object properties: data: type: object properties: type: type: string enum: - hooks attributes: $ref: '#/components/schemas/hooks_attributes' relationships: type: object properties: site: type: object properties: data: $ref: '#/components/schemas/resource_identifier' required: - site required: - type - attributes - relationships required: - data responses: '201': description: Success, webhook created content: application/vnd.api+json: schema: $ref: '#/components/schemas/hooks_show_response' '401': description: Unauthorized, Authorization header is missing or invalid content: application/vnd.api+json: schema: $ref: '#/components/schemas/errors_unauthorized' '403': description: Forbidden, insufficient permission to access the resource content: application/vnd.api+json: schema: $ref: '#/components/schemas/errors_forbidden' '422': description: Unprocessable Entity, invalid parameters content: application/vnd.api+json: schema: $ref: '#/components/schemas/errors_unprocessable' security: - Bearer: [] components: schemas: hooks_attributes: type: object properties: event: type: string enum: - purchase - form_submission - tag_added - tag_removed - payment_succeeded - order_created target_url: type: string created_at: type: string format: date-time readOnly: true description: ISO 8601 date-time, read only updated_at: type: string format: date-time readOnly: true description: ISO 8601 date-time, read only resource_id: type: - integer - 'null' required: - event - target_url resource_identifier: type: object properties: id: type: string type: type: string required: - id - type hooks_show_response: type: object properties: data: type: object properties: id: type: string type: type: string enum: - hooks attributes: $ref: '#/components/schemas/hooks_attributes' relationships: type: object properties: site: type: object properties: data: $ref: '#/components/schemas/resource_identifier' errors_unauthorized: type: object properties: errors: type: array items: $ref: '#/components/schemas/errors_attributes' errors_forbidden: type: object properties: errors: type: array items: $ref: '#/components/schemas/errors_attributes' errors_unprocessable: type: object properties: errors: type: array items: $ref: '#/components/schemas/errors_attributes' errors_attributes: type: object properties: status: type: string source: type: object nullable: true properties: pointer: type: string title: type: string detail: type: string securitySchemes: Bearer: type: http scheme: bearer ````