> ## Documentation Index > Fetch the complete documentation index at: https://docs.anny.co/llms.txt > Use this file to discover all available pages before exploring further. # Receive a post-call webhook from HiDesk > Sent by HiDesk after a call completes, to deliver final call status, transcript, summary, and recording link. ### Authentication The request body is signed by HiDesk with HMAC-SHA256 using the shared secret. The hex-encoded digest is sent in the `X-HiDesk-Signature` header. anny verifies the signature against the **raw** request body before any JSON parsing. If verification fails the response is `401 Unauthorized`. ### Delivery requirements - Deliver within **60 seconds** of call end. - Retry **at least 3×** with exponential backoff on any non-2xx response or timeout. - anny deduplicates on `provider_call_id`; redelivery of the same payload is safe and idempotent. ### Correlation `provider_call_id` is the same value HiDesk sent on `POST /api/voice/incoming-call`. anny uses it to look up the originating call session and merge the metadata into the resulting Customer Communication record. ## OpenAPI ````yaml /developers/openapi/admin-internal.openapi.json post /api/voice/webhook openapi: 3.1.0 info: title: admin-api version: '1.0' description: >- The Admin API gives you **full programmatic access** to your anny organization. It is built for **server-side integrations** — backend services, automation scripts, and custom tooling that act on behalf of your team. --- ## When to use the Admin API Use the Admin API when you need to **drive workflows from your own systems**: - **Sync membership data** — create or update customers, assign them to communities, reflect subscription status from an external CRM - **Create bookings programmatically** — build back-office tools or automate repeat reservations without going through the customer checkout - **Issue and forward invoices** — generate invoices, send them to customers, or push them to your accounting system - **React to real-time events** — pair the API with [Webhooks](/developers/guides/admin/webhooks) to trigger side effects whenever a booking is created, cancelled, or checked in - **Drive display panels** — push live occupancy and schedule data to digital signage or lobby displays Combined with [webhook subscriptions](/developers/guides/admin/webhooks), you can build fully automated, event-driven workflows without polling. --- ## Authentication Generate a long-lived API token directly in the admin dashboard under **Organization Settings → API**. All requests require it in the `Authorization` header: ``` Authorization: Bearer {access_token} ``` Every endpoint is **organization-scoped**. Pass your organization ID as a query parameter on every request: ``` ?o={organization_id} ``` See the [Authentication guide](/developers/guides/authentication) for token scopes and the full OAuth2 flow. --- ## Admin API vs Customer API | | Admin API | Customer API | |---|---|---| | **Use case** | Server-side automation, backend tooling | End-user apps, booking widgets | | **Auth** | Required — API token or OAuth2 | Optional — many endpoints work without a token | | **Identifiers** | Immutable UUIDs and integer IDs | Slugs, booking numbers, order numbers | | **Access** | Full read/write | Public and customer-owned data only | → [Go to the Customer API](/developers/api-reference/customer) --- ## Resource Identifiers The Admin API uses **immutable IDs** — UUIDs for most entities, integers for legacy ones. These are safe to store in external systems and never change, even if an organization renames a resource. --- ## Starting Points | Guide | What it covers | |---|---| | [Getting Started](/developers) | First steps and quickstart | | [JSON:API Conventions](/developers/guides/json-api-conventions) | Request and response format | | [Authentication](/developers/guides/authentication) | API tokens, OAuth2, scopes | | [Availability & Booking Search](/developers/guides/availability) | Search open slots and timeslots | | [Admin Booking Creation](/developers/guides/admin/booking-creation) | Create bookings from the back office | | [Admin Booking Edit](/developers/guides/admin/booking-edit) | Edit resource, dates, fields, add-ons, and sub-bookings | | [Admin Booking Lifecycle](/developers/guides/admin/booking-lifecycle) | Status changes, check-in, cancellations | | [Invoices](/developers/guides/admin/invoices) | Create, send, and manage invoices | | [Customer Management](/developers/guides/admin/customer-management) | Create and manage customer records | | [Booking Calendars](/developers/guides/admin/calendar-events) | Custom calendar events | | [Timeslot Management](/developers/guides/admin/timeslot-management) | Manage timeslot CRUD, recurrence, allocations, and rescheduling | | [Broadcast Campaigns](/developers/guides/admin/broadcasting) | Email and push campaigns | | [Exports](/developers/guides/admin/exports) | Export bookings and customer data | | [Webhooks & Events](/developers/guides/admin/webhooks) | Subscribe to real-time events | --- ## Base URLs | Environment | URL | |---|---| | Production | `https://b.anny.co` | | Gov-Cloud | `https://b.anny.eu` | contact: name: anny GmbH url: https://anny.co email: support@anny.co servers: - url: https://b.anny.co description: Production - url: https://b.anny.eu description: Gov-Cloud security: - Bearer: [] tags: - name: Booking Quotas - name: Orders - name: Organizations - name: Table Configuration - name: Test-Results - name: User Settings - name: Terminal Locations - name: Terminal Readers - name: Connection Tokens - name: Views - name: Voice Integration paths: /api/voice/webhook: post: tags: - Voice Integration summary: Receive a post-call webhook from HiDesk description: > Sent by HiDesk after a call completes, to deliver final call status, transcript, summary, and recording link. ### Authentication The request body is signed by HiDesk with HMAC-SHA256 using the shared secret. The hex-encoded digest is sent in the `X-HiDesk-Signature` header. anny verifies the signature against the **raw** request body before any JSON parsing. If verification fails the response is `401 Unauthorized`. ### Delivery requirements - Deliver within **60 seconds** of call end. - Retry **at least 3×** with exponential backoff on any non-2xx response or timeout. - anny deduplicates on `provider_call_id`; redelivery of the same payload is safe and idempotent. ### Correlation `provider_call_id` is the same value HiDesk sent on `POST /api/voice/incoming-call`. anny uses it to look up the originating call session and merge the metadata into the resulting Customer Communication record. operationId: post-voice-webhook parameters: - schema: type: string pattern: ^[A-Fa-f0-9]{64}$ in: header name: X-HiDesk-Signature required: true description: >- Hex-encoded HMAC-SHA256 of the raw request body, computed with the shared HiDesk integration secret. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - provider_call_id - event - status - start_time - end_time - duration_seconds - provider_call_url properties: provider_call_id: type: string maxLength: 255 description: >- HiDesk's unique identifier for this call. Must match the value sent on `POST /api/voice/incoming-call`. example: hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P event: type: string enum: - call.completed description: >- Event type. Currently the only supported value is `call.completed`. status: type: string enum: - completed - missed - error description: > Final call status: - `completed` — call connected and ended normally. - `missed` — caller hung up before agent engagement. - `error` — the agent or telephony layer raised an error during the call. start_time: type: string format: date-time description: Call start timestamp in ISO 8601 (UTC). example: '2026-05-11T14:30:22Z' end_time: type: string format: date-time description: Call end timestamp in ISO 8601 (UTC). example: '2026-05-11T14:33:47Z' duration_seconds: type: integer minimum: 0 description: >- Total connected call duration in seconds (telephony connect → telephony hangup). example: 205 transfer_duration_seconds: type: integer minimum: 0 description: >- Portion of `duration_seconds` spent on a live-agent transfer, if any. example: 0 transcript: type: - string - 'null' description: >- Full conversation transcript. `null` if transcription is disabled for this organization or the call did not produce text (e.g. missed). summary: type: - string - 'null' description: >- AI-generated call summary. `null` if summarization is disabled or no useful content was produced. recording_url: type: - string - 'null' format: uri description: >- URL to the raw WAV recording. `null` if recording is disabled. The link is short-lived; anny stores its own copy on receipt. provider_call_url: type: string format: uri description: >- Direct link to view this call in the HiDesk UI. Surfaced in the anny admin dashboard. example: https://app.hidesk.com/calls/hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P examples: completed-call: summary: Completed call with transcript and recording value: provider_call_id: hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P event: call.completed status: completed start_time: '2026-05-11T14:30:22Z' end_time: '2026-05-11T14:33:47Z' duration_seconds: 205 transfer_duration_seconds: 0 transcript: >- Agent: Hallo, hier ist Glow & Co… Caller: Ich hätte gerne einen Termin am Freitag… summary: >- Caller booked a haircut appointment for Friday 16:00 with stylist Anna. recording_url: >- https://recordings.hidesk.com/r/hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P.wav provider_call_url: https://app.hidesk.com/calls/hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P missed-call: summary: Caller hung up before the agent engaged value: provider_call_id: hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P event: call.completed status: missed start_time: '2026-05-11T14:30:22Z' end_time: '2026-05-11T14:30:29Z' duration_seconds: 7 transfer_duration_seconds: 0 transcript: null summary: null recording_url: null provider_call_url: https://app.hidesk.com/calls/hd_01HZ4T8K5W3N6R8VYJ7A2QXM9P responses: '200': description: >- OK — payload received and processed synchronously. Equivalent to `202` for retry purposes. '202': description: >- Accepted — payload received and queued for processing. anny does not block on transcript/recording fetches. '401': description: >- Unauthorized — `X-HiDesk-Signature` is missing or does not match an HMAC-SHA256 of the raw request body. '404': description: >- Not Found — `provider_call_id` does not correspond to any known incoming call. Safe to stop retrying. '422': description: >- Validation error — one or more fields failed validation (see request body schema). security: - HiDeskSignature: [] components: securitySchemes: Bearer: type: oauth2 flows: authorizationCode: authorizationUrl: https://auth.anny.co/oauth/authorize tokenUrl: https://auth.anny.co/oauth/token refreshUrl: https://auth.anny.co/oauth/token/refresh scopes: {} HiDeskSignature: type: apiKey in: header name: X-HiDesk-Signature description: > HMAC-SHA256 signature of the raw request body, computed with the shared HiDesk integration secret and sent as a lowercase hex string. Verified by anny before JSON parsing. Mismatch → `401 Unauthorized`. ````