> ## Documentation Index > Fetch the complete documentation index at: https://docs.sitevisit.app/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook endpoint > Subscribe a new URL to events for this account. The `signingSecret` is included in the response **exactly once** — store it now. To rotate, delete the endpoint and create a new one. URLs must be HTTPS in production (HTTP allowed only for `localhost` during local development). Pass an `Idempotency-Key` for safe retries. ## OpenAPI ````yaml /api-reference/openapi.json post /webhook-endpoints openapi: 3.1.0 info: title: SiteVisit AI API version: 1.0.0 description: >- Public REST API for SiteVisit AI. Read and write properties, site visits, and action items from your account. ## Authentication Authenticate with a `Bearer sv_live_...` token issued in Settings → Developers. Two key modes are supported: - **Live keys (`sv_live_*`)** — operate on your real customer data. Counts against plan limits, fires real webhooks + PostHog activation events. - **Test keys (`sv_test_*`)** — operate on a parallel sandbox dataset (every resource is tagged `isTest=true`). Test data is free + unmetered, never counts against plan limits, and never crosses into live data. Use for development + integration testing without touching production. Test-mode webhook endpoints (configured with `mode=test` in the Settings UI) only receive events triggered by test keys; live endpoints only receive live events. Webhook payloads include a `livemode: bool` flag so receivers can branch without parsing the resource. contact: name: SiteVisit AI Support email: support@sitevisit.app servers: - url: https://sitevisit.app/api/v1 description: Production security: - bearerAuth: [] paths: /webhook-endpoints: post: summary: Create a webhook endpoint description: >- Subscribe a new URL to events for this account. The `signingSecret` is included in the response **exactly once** — store it now. To rotate, delete the endpoint and create a new one. URLs must be HTTPS in production (HTTP allowed only for `localhost` during local development). Pass an `Idempotency-Key` for safe retries. parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: >- Display label shown in Settings → Developers + on delivery logs. url: type: string format: uri description: >- HTTPS endpoint to POST events to. HTTP allowed only for `localhost` URLs in development. events: type: array items: type: string description: >- Subset of event types to subscribe to. Omit or pass `[]` to subscribe to **all** event types — useful for a generic ingest endpoint. required: - name - url additionalProperties: false responses: '201': description: >- Endpoint created. Response includes the `signingSecret` exactly once. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointWithSecret' '400': description: >- Validation error — invalid URL, unknown event type, or missing required field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Another request with the same Idempotency-Key is still in flight. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Idempotency-Key already used with a different request body. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional idempotency key, scoped to the authenticated account. Repeating a write with the same key + same body returns the original response; same key + different body returns 422 idempotency_key_in_use. schema: type: string maxLength: 255 schemas: WebhookEndpointWithSecret: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object properties: signingSecret: type: string description: >- Secret used to verify webhook signatures (HMAC-SHA256, Stripe pattern). **Shown exactly once at creation** — store it now. Rotate by deleting + recreating the endpoint. required: - signingSecret ErrorResponse: type: object properties: error: type: object properties: code: type: string example: invalid_api_key message: type: string example: The API key provided is invalid, revoked, or doesn't exist. docs_url: type: string format: uri request_id: type: string example: req_abc123 required: - code - message - docs_url - request_id required: - error WebhookEndpoint: type: object properties: id: type: string name: type: string url: type: string format: uri events: type: array items: type: string description: >- Events this endpoint subscribes to. An empty array means **all events** — the endpoint will receive every event type. See the Webhooks guide for the full event catalogue. mode: type: string enum: - live - test description: >- Which traffic class this endpoint receives. `live` endpoints fire on real customer activity; `test` endpoints only fire on activity triggered by `sv_test_*` API keys. Lets integrators wire a localhost endpoint against test mode without it ever receiving real-customer traffic. disabled: type: boolean description: >- When true, the endpoint is paused — events are not delivered, but the row + signing secret remain so it can be re-enabled later. createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - name - url - events - mode - disabled - createdAt - updatedAt securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: sv_live_xxx (or sv_test_xxx for sandbox mode) description: >- Bearer API key. Two modes: `sv_live_*` for production data, `sv_test_*` for a parallel sandbox dataset that doesn't count against plan limits. Issued from Settings → Developers in the SiteVisit app. ````