> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.aura-app.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook subscription > Subscribe to real-time events from Aura. **How it works:** 1. Create a subscription with your endpoint URL 2. Store the `secret` from this response — it is returned **only here**, never by `GET /v1/webhooks` or `GET /v1/webhooks/{id}`. If you lose it, rotate it with `POST /v1/webhooks/{id}/rotate-secret`. 3. When events occur, Aura sends HTTP POST requests to your URL 4. Verify requests using the `X-Aura-Signature` header **Security:** - Target URL must use HTTPS (no HTTP allowed) - Each webhook is signed with HMAC-SHA256 - Use the secret to verify request authenticity **Payload Format:** ```json { "event": "call.booked", "created_at": "2026-01-17T08:00:00Z", "data": { /* event-specific data */ }, "organization_id": "org_xxx", "idempotency_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } ``` **Signature Verification:** ```javascript const crypto = require('crypto'); const signature = crypto .createHmac('sha256', YOUR_SECRET) .update(JSON.stringify(payload)) .digest('hex'); ``` **Retry Policy:** - Failed deliveries are retried 3 times - Backoff: 1s, 5s, 15s - Subscriptions with repeated failures may be disabled **Exactly-once processing (`idempotency_key`):** - Every envelope carries an `idempotency_key` that is stable across retries of the same event. If your endpoint commits its side effect then crashes before returning 2xx, the redelivery carries the **same** key. - Enforce exactly-once by adding a `(subscription_id, idempotency_key)` unique constraint on your side and dropping the row on conflict. - The key is inside the signed body, so the HMAC signature covers it. Subscribe to real-time events from Aura. **How it works:** 1. Create a subscription with your endpoint URL 2. Store the `secret` from this response — it is returned **only here**, never by `GET /v1/webhooks` or `GET /v1/webhooks/{id}`. If you lose it, rotate it with `POST /v1/webhooks/{id}/rotate-secret`. 3. When events occur, Aura sends HTTP POST requests to your URL 4. Verify requests using the `X-Aura-Signature` header **Security:** * Target URL must use HTTPS (no HTTP allowed) * Each webhook is signed with HMAC-SHA256 * Use the secret to verify request authenticity **Payload Format:** ```json theme={null} { "event": "call.booked", "created_at": "2026-01-17T08:00:00Z", "data": { /* event-specific data */ }, "organization_id": "org_xxx", "idempotency_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } ``` **Signature Verification:** ```javascript theme={null} const crypto = require('crypto'); const signature = crypto .createHmac('sha256', YOUR_SECRET) .update(JSON.stringify(payload)) .digest('hex'); ``` **Retry Policy:** * Failed deliveries are retried 3 times * Backoff: 1s, 5s, 15s * Subscriptions with repeated failures may be disabled **Exactly-once processing (`idempotency_key`):** * Every envelope carries an `idempotency_key` that is stable across retries of the same event. If your endpoint commits its side effect then crashes before returning 2xx, the redelivery carries the **same** key. * Enforce exactly-once by adding a `(subscription_id, idempotency_key)` unique constraint on your side and dropping the row on conflict. * The key is inside the signed body, so the HMAC signature covers it. ## OpenAPI ````yaml openapi.json POST /v1/webhooks openapi: 3.1.0 info: contact: email: support@aura-app.ai name: Aura Support description: >- # Aura Partner Integrations API > **Alpha Release** - This API is under active development. Endpoints, request/response schemas, and behaviors may change without prior notice. We recommend pinning to specific response fields you need and handling unknown fields gracefully. Enterprise REST API for external partner integrations including commission platforms, external mobile apps, and client booking widgets. ## MCP Connector Aura also exposes a **Model Context Protocol** server at `/mcp` so AI assistants (Claude, ChatGPT) can answer questions about a user's own sales data. If you are building an assistant integration rather than a server-to-server one, that is almost certainly the surface you want — it is task-shaped ("prep me for my next call") rather than resource-shaped, and it handles auth per-user. Read-only. OAuth 2.1 + PKCE, with Clerk as the authorization server; discover it from `/.well-known/oauth-protected-resource`. Setup guide: https://docs.api.aura-app.ai/mcp-connector ## Authentication Authenticated endpoints support two authentication methods: **1. API Key (for partners and integrations):** ``` Authorization: Bearer aura_pk_live_xxxxxxxxxxxxxxxx ``` Get your API key from the Aura dashboard at Settings > API Keys. **2. Clerk JWT (for mobile and web apps):** ``` Authorization: Bearer ``` Use Clerk's authentication SDK to obtain a JWT token with org claims. ## Rate Limiting - **Per API Key:** 100 requests/minute - **Per Organization:** 1000 requests/minute Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests allowed - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp when limit resets These counters are held per serving instance, so under concurrency the effective ceiling is higher than the number above and the headers describe one instance's view rather than a global total. Treat a 429 as backpressure to obey and pace your client to the documented rate — but do not rely on us to reject your 101st request, and do not derive a global remaining-quota figure from the headers. The limit may become globally enforced without notice, so a client that stays within it will not be affected when that happens. ## Pagination List endpoints support cursor-based pagination: - `limit`: Number of results per page (default: 50, max: 100) - `cursor`: Opaque cursor for next page ## Error Handling All errors follow a standard format: ```json { "success": false, "error": "Error message", "code": "ERROR_CODE" } ``` Common HTTP status codes: - **400** Bad Request - Invalid input (`VALIDATION_ERROR`) - **401** Unauthorized - Missing or invalid API key (`AUTHENTICATION_ERROR`) - **402** Payment Required - The key is valid, but the organization's subscription is not active (`PAYMENT_REQUIRED`). Every authenticated endpoint can return this. Retrying will not help until the account's payment method is updated in Aura; surface it to the account owner rather than treating it as an auth failure. - **403** Forbidden - Insufficient permissions (`AUTHORIZATION_ERROR`) - **404** Not Found - Resource not found (`NOT_FOUND`) - **409** Conflict - Resource state prevents the operation (`CONFLICT`) - **413** Payload Too Large - Request body exceeds 256KB (`PAYLOAD_TOO_LARGE`) - **429** Too Many Requests - Rate limit exceeded (`RATE_LIMIT_EXCEEDED`) - **500** Internal Server Error - Server error (`INTERNAL_ERROR`) ## Webhooks Subscribe to real-time events using the Webhooks API. All webhook payloads are signed with HMAC-SHA256 for security verification. Delivery is at-least-once. Every payload carries an `idempotency_key` that is stable across retries of the same event, so you can enforce exactly-once with a `(subscription_id, idempotency_key)` unique constraint on your side. For full documentation, visit [docs.aura-app.ai/api](https://docs.aura-app.ai/api) license: name: Proprietary title: Aura Partner Integrations API version: 1.0.0-alpha servers: - description: Production url: https://api.aura-app.ai - description: Staging url: https://staging-api.aura-app.ai - description: Local Development url: http://localhost:3001 security: - bearerAuth: [] tags: - description: Lead management operations name: Leads - description: Call booking and management name: Calls - description: Booking link configuration (read-only) name: Booking Links - description: Product catalog (read-only) name: Products - description: Payment tracking (read-only) name: Payments - description: Public booking creation name: Bookings - description: Real-time event subscriptions and webhook management name: Webhooks - description: >- Team member information for commission attribution. **Alpha** - schema may change without notice. name: Team (Alpha) - description: >- Dashboard analytics, lead source attribution, and objection analysis. **Alpha** - schema may change without notice. name: Analytics (Alpha) - description: System endpoints (health checks) name: System paths: /v1/webhooks: post: tags: - Webhooks summary: Create webhook subscription description: >- Subscribe to real-time events from Aura. **How it works:** 1. Create a subscription with your endpoint URL 2. Store the `secret` from this response — it is returned **only here**, never by `GET /v1/webhooks` or `GET /v1/webhooks/{id}`. If you lose it, rotate it with `POST /v1/webhooks/{id}/rotate-secret`. 3. When events occur, Aura sends HTTP POST requests to your URL 4. Verify requests using the `X-Aura-Signature` header **Security:** - Target URL must use HTTPS (no HTTP allowed) - Each webhook is signed with HMAC-SHA256 - Use the secret to verify request authenticity **Payload Format:** ```json { "event": "call.booked", "created_at": "2026-01-17T08:00:00Z", "data": { /* event-specific data */ }, "organization_id": "org_xxx", "idempotency_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } ``` **Signature Verification:** ```javascript const crypto = require('crypto'); const signature = crypto .createHmac('sha256', YOUR_SECRET) .update(JSON.stringify(payload)) .digest('hex'); ``` **Retry Policy:** - Failed deliveries are retried 3 times - Backoff: 1s, 5s, 15s - Subscriptions with repeated failures may be disabled **Exactly-once processing (`idempotency_key`):** - Every envelope carries an `idempotency_key` that is stable across retries of the same event. If your endpoint commits its side effect then crashes before returning 2xx, the redelivery carries the **same** key. - Enforce exactly-once by adding a `(subscription_id, idempotency_key)` unique constraint on your side and dropping the row on conflict. - The key is inside the signed body, so the HMAC signature covers it. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWebhookSubscriptionBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionCreatedResponse' description: Webhook subscription created successfully '400': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: Invalid request (e.g., non-HTTPS URL) '401': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: Invalid or missing API key '402': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The organization's subscription is not active headers: X-Request-Id: description: Request identifier for support schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The API key does not have the required scope headers: X-Request-Id: description: Request identifier for support schema: type: string '408': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- The request exceeded its processing time limit. Check the outcome before retrying a write headers: X-Request-Id: description: Request identifier for support schema: type: string '413': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The request body exceeds 256KB headers: X-Request-Id: description: Request identifier for support schema: type: string '429': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: Rate limit exceeded. Wait before retrying headers: Retry-After: description: Seconds to wait before retrying schema: type: string X-RateLimit-Limit: description: Requests allowed in the current window schema: type: string X-RateLimit-Remaining: description: Requests remaining in the current window schema: type: string X-RateLimit-Reset: description: Window reset as a Unix timestamp schema: type: string X-Request-Id: description: Request identifier for support schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- Unexpected server failure. Include the request identifier when contacting support headers: X-Request-Id: description: Request identifier for support schema: type: string security: - bearerAuth: [] components: schemas: CreateWebhookSubscriptionBody: properties: event_type: description: Event type to subscribe to enum: - lead.created - lead.updated - lead.status_changed - lead.deleted - call.booked - call.updated - call.started - call.completed - call.canceled - call.rescheduled - call.closer_reassigned - call.no_show - call.analysis_completed - payment.succeeded - payment.failed - payment.refunded example: call.booked type: string target_url: description: >- HTTPS URL where webhook payloads will be sent (must be publicly accessible) example: https://api.example.com/webhooks/aura format: uri type: string required: - event_type - target_url type: object WebhookSubscriptionCreatedResponse: properties: data: $ref: '#/components/schemas/WebhookSubscriptionWithSecret' success: enum: - true type: boolean required: - success - data type: object WebhookErrorResponse: properties: code: description: Machine-readable error code example: WEBHOOK_NOT_FOUND type: string error: description: Human-readable error message example: Webhook subscription not found type: string success: enum: - false type: boolean required: - success - error type: object MiddlewareErrorResponse: properties: code: type: string error: type: string requestId: type: string success: enum: - false type: boolean required: - success - error - code type: object WebhookSubscriptionWithSecret: allOf: - $ref: '#/components/schemas/WebhookSubscription' - properties: secret: description: >- HMAC-SHA256 signing secret for verifying deliveries. Returned exactly once, here, on creation — store it now. It is never included in list or get responses. If lost, rotate it via POST /v1/webhooks/{id}/rotate-secret. example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 type: string required: - secret type: object WebhookSubscription: properties: created_at: description: When subscription was created (ISO 8601) example: '2026-01-17T08:00:00Z' format: date-time type: string event_type: description: >- Event type this subscription listens to. Null on multi-event subscriptions, which use `event_types` instead. example: call.booked nullable: true type: string event_types: description: >- Event types for a multi-event subscription. Null on single-event subscriptions, which use `event_type`. Subscriptions created through this API are always single-event. example: - call.booked - call.completed items: type: string nullable: true type: array id: description: Unique identifier for the webhook subscription example: 550e8400-e29b-41d4-a716-446655440000 type: string target_url: description: >- URL where webhook payloads will be sent. Null for subscriptions that deliver somewhere other than an HTTP endpoint (for example the in-app Slack integration), which cannot be created or modified through this API. example: https://api.example.com/webhooks/aura format: uri nullable: true type: string required: - id - event_type - target_url - created_at type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.