> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackone.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook > Registers a webhook endpoint in the project and returns it with the signing secret used to verify payload signatures. The webhook receives the events listed in `events`. Connector events are subscribed separately: add the webhook `id` to `webhook_ids` in the `event_config` of a connector profile. ## OpenAPI ````yaml post /v2/webhooks openapi: 3.1.0 info: title: StackOne description: The documentation for the StackOne API version: 1.0.0 contact: {} servers: - url: https://api.stackone.com security: [] tags: - name: Accounts description: View and manage linked accounts. - name: Connector Profiles description: >- View and manage connector profiles for the project: the authentication, enabled actions, data sync and events of each configured connector. - name: Connectors description: Retrieve metadata for connectors. - name: Webhooks description: Configure and manage webhooks. - name: Data Sync description: View data-sync configs, schedules, runs, and event subscriptions. paths: /v2/webhooks: post: tags: - Webhooks summary: Create a webhook description: >- Registers a webhook endpoint in the project and returns it with the signing secret used to verify payload signatures. The webhook receives the events listed in `events`. Connector events are subscribed separately: add the webhook `id` to `webhook_ids` in the `event_config` of a connector profile. operationId: create_webhook parameters: - name: expand required: false in: query description: >- A comma-separated list of additional fields to expand. Supported values: `provider_events` (the per-provider event configuration). These are returned as `null` unless requested. schema: nullable: true example: provider_events type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookDto' responses: '201': description: The webhook was created. content: application/json: schema: $ref: '#/components/schemas/WebhookDetailResource' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized access. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '408': description: The request has timed out. headers: Retry-After: description: A time in seconds after which the request can be retried. schema: type: string content: application/json: schema: $ref: '#/components/schemas/RequestTimedOutResponse' '409': description: Conflict with current state. content: application/json: schema: $ref: '#/components/schemas/ConflictResponse' '422': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityResponse' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' '500': description: Server error while executing the request. content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' '501': description: This functionality is not implemented. content: application/json: schema: $ref: '#/components/schemas/NotImplementedResponse' '502': description: Bad gateway error. content: application/json: schema: $ref: '#/components/schemas/BadGatewayResponse' security: - basic: [] components: schemas: CreateWebhookDto: type: object properties: webhook_url: type: string description: >- The https URL events are delivered to. `localhost` and numeric IP addresses are rejected, and a hostname that does not resolve in DNS fails the request with a 502. example: https://example.com/stackone/webhooks events: type: array example: - account.created - account.updated - account.deleted description: >- The events the webhook is subscribed to. Send an empty list for a webhook that only receives connector events routed to it from a connector profile. items: $ref: '#/components/schemas/WebhookEventType' label: type: string description: A display label for the webhook. default: webhook example: Production nullable: true provider_events: type: object additionalProperties: type: object description: >- The unified events sourced from the provider, keyed by unified event name. additionalProperties: $ref: '#/components/schemas/WebhookProviderEventConfigResource' description: >- The per-provider event configuration, keyed by provider key and then by unified event name. `programmatic` and `manual` provider events the connector does not support are ignored. nullable: true required: - webhook_url - events WebhookDetailResource: type: object properties: id: type: string description: The unique identifier of the webhook. label: type: string description: The display label of the webhook. webhook_url: type: string description: The URL webhook events are delivered to. events: description: >- The unified event names the webhook is subscribed to (e.g. `employee.created`). type: array items: type: string status: description: The status of the webhook. x-speakeasy-unknown-values: allow allOf: - $ref: '#/components/schemas/StatusType' status_reasons: description: >- The reasons explaining the current status; empty when none are recorded. type: array items: $ref: '#/components/schemas/WebhookStatusReasonResource' provider_events: type: object nullable: true additionalProperties: type: object description: >- The unified events sourced from the provider, keyed by unified event name. additionalProperties: $ref: '#/components/schemas/WebhookProviderEventConfigResource' description: >- The per-provider event configuration, keyed by provider key and then by unified event name. Only resolved when `expand=provider_events` is requested; `null` otherwise. created_at: type: string format: date-time description: When the webhook was created. updated_at: type: string format: date-time description: When the webhook was last updated. signing_secret: type: string nullable: true description: >- The secret used to sign webhook payloads, for signature verification; `null` when none is stored. required: - id - label - webhook_url - events - status - status_reasons - provider_events - created_at - updated_at - signing_secret BadRequestResponse: type: object properties: statusCode: type: number description: HTTP status code example: 400 message: type: string description: Error message example: Bad Request timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time data: description: Error details nullable: true type: object allOf: - $ref: '#/components/schemas/UnifiedError' provider_errors: description: List of provider-specific errors nullable: true type: array items: $ref: '#/components/schemas/ProviderError' required: - statusCode - message - timestamp UnauthorizedResponse: type: object properties: statusCode: type: number description: HTTP status code example: 401 message: type: string description: Error message example: Unauthorized timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp ForbiddenResponse: type: object properties: statusCode: type: number description: HTTP status code example: 403 message: type: string description: Error message example: Forbidden resource timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp NotFoundResponse: type: object properties: statusCode: type: number description: HTTP status code example: 404 message: type: string description: Error message example: Not Found timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp RequestTimedOutResponse: type: object properties: statusCode: type: number description: HTTP status code example: 408 message: type: string description: Error message example: Request timed out timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp ConflictResponse: type: object properties: statusCode: type: number description: HTTP status code example: 409 message: type: string description: Error message example: Conflict timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp UnprocessableEntityResponse: type: object properties: statusCode: type: number description: HTTP status code example: 422 message: type: string description: Error message example: Unprocessable Entity timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp TooManyRequestsResponse: type: object properties: statusCode: type: number description: HTTP status code example: 429 message: type: string description: Error message example: Too many requests timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp InternalServerErrorResponse: type: object properties: statusCode: type: number description: HTTP status code example: 500 message: type: string description: Error message example: Internal server error timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp NotImplementedResponse: type: object properties: statusCode: type: number description: HTTP status code example: 501 message: type: string description: Error message example: Not Implemented timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp BadGatewayResponse: type: object properties: statusCode: type: number description: HTTP status code example: 502 message: type: string description: Error message example: Bad Gateway timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp WebhookEventType: type: string description: A unified webhook event type. enum: - account.created - account.updated - account.deleted - hris_employees.created - hris_employees.updated - hris_employees.deleted - hris_employments.created - hris_employments.updated - hris_employments.deleted - hris_time_off.created - hris_time_off.updated - hris_time_off.deleted - hris_tasks.created - hris_tasks.updated - hris_tasks.deleted - hris_shifts.created - hris_shifts.updated - hris_shifts.deleted - ats_assessments.created - ats_background_checks.created - ats_candidates.created - ats_candidates.updated - ats_candidates.deleted - ats_applications.created - ats_applications.updated - ats_applications.deleted - ats_interviews.created - ats_interviews.updated - ats_interviews.deleted - ats_jobs.created - ats_jobs.updated - ats_jobs.deleted - ats_job_postings.created - ats_job_postings.updated - ats_job_postings.deleted - ats_users.created - ats_users.updated - ats_users.deleted - ats_lists.created - ats_lists.updated - ats_lists.deleted - crm_contacts.created - crm_contacts.updated - crm_contacts.deleted - crm_accounts.created - crm_accounts.updated - crm_accounts.deleted - lms_completions.created - lms_completions.updated - lms_completions.deleted - lms_content.created - lms_content.updated - lms_content.deleted - lms_assignments.created - lms_assignments.updated - lms_assignments.deleted - lms_courses.created - lms_courses.updated - lms_courses.deleted - lms_users.created - lms_users.updated - lms_users.deleted - documents_files.created - documents_files.updated - documents_files.deleted - documents_folders.created - documents_folders.updated - documents_folders.deleted - documents_drives.created - documents_drives.updated - documents_drives.deleted - screening_results.created - screening_results.updated - screening_results.deleted WebhookProviderEventConfigResource: type: object properties: synthetic: description: >- The StackOne-synthesised source of the event, when the provider has one. nullable: true type: object allOf: - $ref: '#/components/schemas/WebhookEventToggleResource' programmatic: description: The provider events wired up programmatically by StackOne. nullable: true type: object allOf: - $ref: '#/components/schemas/WebhookEventSourceResource' manual: description: The provider events requiring manual setup in the external system. nullable: true type: object allOf: - $ref: '#/components/schemas/WebhookEventSourceResource' StatusType: type: string enum: - active - inactive - suspended - archived - expired - error - unmapped_value - null WebhookStatusReasonResource: type: object properties: code: type: string description: A machine-readable status code. nullable: true description: type: string description: A human-readable explanation of the status. nullable: true timestamp: type: string format: date-time description: When this reason was recorded. required: - timestamp UnifiedError: type: object properties: statusCode: type: number description: HTTP status code example: 400 nullable: true message: type: string description: Error message example: Bad Request nullable: true headers: type: object description: Response headers example: content-type: application/json x-request-id: 5678c28b211dace4e0a0f9171e6b88c5 nullable: true ProviderError: type: object properties: status: type: number description: HTTP status code of the provider error example: 400 nullable: true url: type: string description: URL that caused the error example: https://api.provider.com/v1/resource nullable: true raw: type: object description: Raw error response from the provider example: message: Invalid input parameters nullable: true headers: type: object description: Response headers example: content-type: application/json x-request-id: 5678c28b211dace4e0a0f9171e6b88c5 nullable: true WebhookEventToggleResource: type: object properties: enabled: type: boolean description: Whether the event is enabled. required: - enabled WebhookEventSourceResource: type: object properties: events: type: object additionalProperties: $ref: '#/components/schemas/WebhookEventToggleResource' description: >- The provider-specific events of this source, keyed by provider event. required: - events securitySchemes: basic: type: http scheme: basic ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.