> ## Documentation Index > Fetch the complete documentation index at: https://docs.growdental.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook endpoint > Registers an HTTPS endpoint to receive signed event deliveries. Requires `webhooks:manage`. Apps may register at most 20 endpoints (`409 limit_exceeded` beyond that). The response includes the endpoint's HMAC signing `secret` **exactly once** — store it securely; it cannot be retrieved again (idempotent replays of the create response deliberately omit it). To rotate a secret, create a new endpoint, migrate, then delete the old one. ## OpenAPI ````yaml /openapi.yaml post /webhook-endpoints openapi: 3.1.0 info: title: GrowDental Partner API version: '2026-07-04' summary: >- Programmatic access to GrowDental's voice-AI calling platform for dental practices. description: > The GrowDental Partner API lets platforms and practice-management systems integrate with GrowDental's voice-AI calling for dental practices: list the practices you have been granted, read call results, fetch recordings, trigger outbound calls, and receive signed webhook events. **Status: early access.** This specification is the published v1 contract. Where the deployed API and this document disagree during early access, the discrepancy is a bug — report it and we will reconcile. ### Access Access is **invite-only**. There is no self-serve signup: partner apps, API keys, and practice grants are issued by the GrowDental team. Contact [partners@growdental.ai](mailto:partners@growdental.ai) to get started. ### Conventions - All request and response bodies are JSON; property names are **snake_case** (`duration_seconds`, `next_cursor`, `enabled_events`). - Errors use one envelope everywhere: `{ "error": "", "message": "" }`. - Requests referencing practices your app has **not** been granted return `404` (never `403`), so practice identifiers cannot be probed. - `GET` endpoints never take request bodies; all filters are query parameters. - Pagination varies by resource: the calls list uses cursor pagination (`limit` + `cursor` in, `data` + `next_cursor` out); the call-requests list uses `limit` + `offset` with a `pagination` object; the practices list is unpaginated. - Every `POST` endpoint honors an `Idempotency-Key` header (24-hour replay window). - Timestamps are ISO 8601 / RFC 3339 UTC strings. ### Rate limits Per API key: **600 requests/minute** by default; bulk write endpoints (call-request creation) have a separate **60 requests/minute** budget. Limited requests receive `429 rate_limited` with a `Retry-After` header (seconds). ### PHI and the BAA gate Scopes that expose protected health information (`transcripts:read`, `recordings:read`, `intake:write`) are hard-gated in code: they return `403 baa_required` until a Business Associate Agreement is on file for your app. Webhook payloads are PHI-minimal by design (IDs, outcomes, and links); PHI travels only over authenticated API pulls. contact: name: GrowDental Partnerships email: partners@growdental.ai url: https://voice.growdental.ai servers: - url: https://voice.growdental.ai/api/partner/v1 description: Production security: - bearerAuth: [] tags: - name: Practices description: Practices your partner app has been granted access to. - name: Calls description: Completed and in-flight calls for granted practices. - name: Recordings description: Short-lived, signed access to call recordings (PHI — BAA required). - name: Call Requests description: Trigger outbound voice-AI calls to one or more contacts. - name: Webhook Endpoints description: Manage the HTTPS endpoints that receive signed event deliveries. paths: /webhook-endpoints: post: tags: - Webhook Endpoints summary: Create a webhook endpoint description: | Registers an HTTPS endpoint to receive signed event deliveries. Requires `webhooks:manage`. Apps may register at most 20 endpoints (`409 limit_exceeded` beyond that). The response includes the endpoint's HMAC signing `secret` **exactly once** — store it securely; it cannot be retrieved again (idempotent replays of the create response deliberately omit it). To rotate a secret, create a new endpoint, migrate, then delete the old one. operationId: createWebhookEndpoint parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookEndpointBody' responses: '201': description: Endpoint created. The `secret` is shown only in this response. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointWithSecret' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: | The `Idempotency-Key` was already used with a different payload (`idempotency_conflict`), or the app already has the maximum number of endpoints (`limit_exceeded`). content: application/json: schema: $ref: '#/components/schemas/Error' examples: idempotencyConflict: value: error: idempotency_conflict message: >- This Idempotency-Key was already used with a different request payload. limitExceeded: value: error: limit_exceeded message: Apps may register at most 20 webhook endpoints. '429': $ref: '#/components/responses/RateLimited' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: | Client-generated unique key (e.g. a UUID) making the POST safely retryable for 24 hours: retries with the same key and payload replay the original response; the same key with a **different** payload is rejected with `409 idempotency_conflict`. Strongly recommended on every POST — required in practice for call-request creation, where a blind retry can dial patients twice. schema: type: string maxLength: 255 example: 018f3c9e-5f7a-7c3e-b1ce-0a1b2c3d4e5f schemas: CreateWebhookEndpointBody: type: object required: - url - enabled_events properties: url: type: string format: uri maxLength: 500 description: >- HTTPS URL that will receive event deliveries. Must be publicly reachable. examples: - https://api.example-pms.com/growdental/webhooks enabled_events: type: array minItems: 1 items: $ref: '#/components/schemas/WebhookEventType' description: Event types to deliver to this endpoint. WebhookEndpointWithSecret: description: >- Returned only from endpoint creation — includes the one-time signing secret. allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object required: - secret properties: secret: type: string description: | HMAC-SHA256 signing secret for this endpoint. Shown **only in this response** — it is stored encrypted and cannot be retrieved again. Use it to verify the `X-GrowDental-Signature` header on every delivery. Error: type: object description: The error envelope used by every non-2xx response. required: - error - message properties: error: type: string description: Stable machine-readable error code. examples: - invalid_api_key - insufficient_scope - baa_required - not_found - rate_limited message: type: string description: >- Human-readable explanation. Do not parse; codes are stable, messages are not. WebhookEventType: type: string description: | Event types deliverable to webhook endpoints. `call_attempt.resolved` and `appointment.booked` are planned (Phase 2) — valid to subscribe to now, but not yet emitted. enum: - call.completed - call.recording.ready - call_request.completed - call_attempt.resolved - appointment.booked WebhookEndpoint: type: object required: - id - url - enabled_events - status - failure_count - created_at - updated_at properties: id: type: string format: uuid url: type: string format: uri enabled_events: type: array items: $ref: '#/components/schemas/WebhookEventType' status: type: string enum: - active - disabled description: | `disabled` endpoints receive no deliveries. Endpoints are auto-disabled after sustained delivery failures; re-enable via PATCH once your receiver is healthy. failure_count: type: integer description: Consecutive failed deliveries; resets on success. created_at: type: string format: date-time updated_at: type: string format: date-time responses: ValidationError: description: | The request body or parameters failed validation (`validation_error`), or the body was not valid JSON (`invalid_json`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: validation_error message: >- contacts.0.phone: must be a valid E.164-compatible phone number (e.g. +18175551234) Unauthorized: description: | Authentication failed: missing/malformed `Authorization` header (`missing_authorization`), unknown key (`invalid_api_key`), or a revoked key (`key_revoked`). content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingAuthorization: value: error: missing_authorization message: >- Missing or malformed Authorization header. Expected: Authorization: Bearer gd_live_... invalidApiKey: value: error: invalid_api_key message: The provided API key is not valid. keyRevoked: value: error: key_revoked message: This API key has been revoked. Forbidden: description: | The key authenticated but is not allowed: the partner app is suspended (`app_suspended`), the key lacks the required scope (`insufficient_scope`), or a PHI scope was used without a signed BAA (`baa_required`). content: application/json: schema: $ref: '#/components/schemas/Error' examples: appSuspended: value: error: app_suspended message: This partner app is suspended. insufficientScope: value: error: insufficient_scope message: 'This API key does not have the required scope: calls:read' baaRequired: value: error: baa_required message: >- The scope recordings:read exposes PHI and requires a signed BAA. Contact support to complete your BAA. RateLimited: description: Rate limit exceeded for this API key. Honor `Retry-After`. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limited message: Rate limit exceeded. Retry after 12 seconds. headers: RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: | Partner API key sent as a Bearer token: ``` Authorization: Bearer gd_live_... ``` Keys are issued by the GrowDental team (invite-only), shown **once** at creation, and stored server-side only as a SHA-256 hash. Key format: `gd_live_` (or `gd_test_`) followed by a 43-character base62 secret (~256 bits of entropy). To rotate, request a new key, deploy it, then ask us to revoke the old one — both keys work during the overlap. ````