> ## Documentation Index > Fetch the complete documentation index at: https://docs.groundtech.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook > Registers a webhook for the authenticated organization. The signing secret is returned only in the creation response. Only `portfolio_wallet.*` event types are accepted. ## OpenAPI ````yaml swagger/swagger-combined.yaml POST /v2/webhooks openapi: 3.0.0 info: title: Ground API description: Core API for portfolio wallets, deposits, withdrawals, and webhooks. version: 2.0.0 servers: - url: https://sandbox.groundtech.co - url: https://production.groundtech.co security: - bearerAuth: [] tags: - name: System description: System health and utility endpoints. - name: Sandbox Faucets description: Sandbox-only test token faucets. - name: Portfolio Wallets description: >- Portfolio wallets with strategy allocation, deposits, withdrawals, and yield positions. - name: Webhook Endpoints description: Webhook endpoint management for portfolio wallet notifications. paths: /v2/webhooks: post: tags: - Webhooks summary: Create a webhook description: > Registers a webhook for the authenticated organization. The signing secret is returned only in the creation response. Only `portfolio_wallet.*` event types are accepted. operationId: createWebhook requestBody: required: true content: application/json: schema: type: object required: - url - events additionalProperties: true properties: url: type: string format: uri example: https://ops.acme-treasury.com/webhooks/ground events: type: array minItems: 1 description: Event types to subscribe to. items: type: string enum: - portfolio_wallet.status_changed - portfolio_wallet.deposit.status_changed - portfolio_wallet.withdrawal.status_changed - portfolio_wallet.withdrawal.payout.status_changed - portfolio_wallet.strategy.status_changed - portfolio_wallet.rebalance.status_changed - portfolio_wallet.risk.alert.triggered - portfolio_wallet.risk.alert.resolved - portfolio_wallet.risk.action.status_changed - portfolio_wallet.risk.unwind.completed description: nullable: true oneOf: - type: string - type: number - type: boolean - type: object additionalProperties: true - type: array items: {} description: >- Optional description. The current API stores truthy JSON values and ignores unknown request fields. example: >- Notify treasury operations when wallet balances or withdrawals change example: url: https://ops.acme-treasury.com/webhooks/ground events: - portfolio_wallet.deposit.status_changed - portfolio_wallet.withdrawal.status_changed - portfolio_wallet.status_changed - portfolio_wallet.rebalance.status_changed description: >- Notify treasury operations when wallet balances or withdrawals change responses: '200': description: Webhook created content: application/json: schema: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object required: - secret example: id: 6b6a0502-9d38-4f94-83fe-06706adbdc51 url: https://ops.acme-treasury.com/webhooks/ground events: - portfolio_wallet.deposit.status_changed - portfolio_wallet.withdrawal.status_changed - portfolio_wallet.rebalance.status_changed secret: >- ad4d5592b46c4b9361f0aa4f3b27fcaa8015751d0417e3993d7f5454652c5ab8 createdAt: '2026-05-01T17:32:08.000Z' '400': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation_error: value: error: 'Unsupported event types: portfolio_wallet.legacy_event' code: validation_error '401': $ref: '#/components/responses/Unauthorized' '409': description: Webhook already exists for this URL content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: duplicate: value: error: A webhook endpoint already exists for this URL code: webhook_duplicate_url '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: schemas: WebhookEndpoint: type: object description: >- A webhook registration. The signing `secret` is only returned in the creation response. required: - id - url - events - createdAt properties: id: type: string format: uuid url: type: string format: uri events: type: array items: type: string description: Subscribed event types. createdAt: type: string format: date-time secret: type: string description: Signing secret. Only returned on creation. Store securely. ErrorResponse: type: object required: - error - code properties: error: type: string description: >- Human-readable error message. May change without notice; do not parse programmatically. code: type: string description: >- Machine-readable error code. Stable across API versions — safe to switch on in client code. enum: - validation_error - unknown_parameters - unsupported_chain - unsupported_token - invalid_destination_address - precision_overflow - invalid_cursor - unauthenticated - forbidden - wallet_not_found - wallet_limit_reached - withdrawal_not_found - deposit_not_found - yield_source_not_found - wallet_projection_unavailable - insufficient_funds - duplicate_request_id - request_id_conflict - invalid_position_weight - invalid_withdrawal_plan - payout_not_found - webhook_not_found - webhook_duplicate_url - withdrawal_not_cancellable - withdrawal_already_cancelled - withdrawal_payout_in_progress - withdrawal_policy_required - workflow_conflict - payout_already_terminal - payout_in_progress - payout_not_retryable - address_book_entry_not_found - address_book_duplicate_entry - address_book_whitelist_violation - rate_limited - rate_limit_exceeded - internal_error - wallet_creation_failed - service_temporarily_unavailable AuthErrorResponse: type: object required: - error properties: error: type: string description: Authentication or authorization error message. message: type: string nullable: true description: Additional auth middleware detail, when present. code: type: string nullable: true enum: - unauthenticated - forbidden description: >- Some auth and scope failures include a stable code; middleware errors may omit it. responses: Unauthorized: description: >- The request is missing a valid bearer token, or the token is invalid or expired. content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' example: error: Unauthenticated request message: Missing or invalid bearer token TooManyRequests: description: >- Rate limit exceeded. Limits are enforced by API key/customer identity and by endpoint class. Retry with backoff; rate-limit headers are not currently emitted. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Rate limit exceeded code: rate_limited InternalServerError: description: >- An unexpected error occurred while processing the request. The request can be safely retried with the same `requestId`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Internal server error code: internal_error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````