> ## Documentation Index > Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook subscription > Register a webhook to receive event notifications. The response includes the `signingSecret` — shown only once — used to verify the `X-Scribe-Api-Signature` header. ## OpenAPI ````yaml /es/scribe-api/openapi-institutional.json post /v1/webhooks openapi: 3.1.0 info: title: Scribe Public API description: >- API REST externa para integración con la plataforma Telepatia. Autentíquese con claves API, establezca el contexto de consulta y consulte sesiones de scribe. version: 0.1.0 servers: - url: https://scribe-api.telepatia.ai description: Production security: - BearerAuth: [] paths: /v1/webhooks: post: tags: - Webhooks summary: Create a webhook subscription description: >- Register a webhook to receive event notifications. The response includes the `signingSecret` — shown only once — used to verify the `X-Scribe-Api-Signature` header. operationId: api_webhook_create_v1_webhooks_post requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWebhookRequest' example: events: - scribe_session.created - scribe_session.completed - scribe_session.error name: Scribe prod webhook url: https://example.com/webhooks/scribe required: true responses: '200': description: Respuesta exitosa content: application/json: schema: $ref: '#/components/schemas/CreateWebhookResponse' '400': description: >- Solicitud incorrecta — parámetros inválidos, fallos de validación o campos faltantes. content: application/json: examples: parameter_missing: summary: Missing required field value: error: type: invalid_request_error code: parameter_missing message: name is required. param: name parameter_invalid: summary: Invalid field value value: error: type: invalid_request_error code: parameter_invalid message: >- idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code. param: idCountry account_invalid: summary: Invalid account value: error: type: invalid_request_error code: account_invalid message: Account has no valid authId. schema: $ref: '#/components/schemas/ErrorResponse' '401': description: No autorizado — clave API faltante o inválida. content: application/json: examples: authentication_required: summary: Invalid or missing API key value: error: type: authentication_error code: authentication_required message: Invalid API key. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: examples: permission_denied: summary: Caller lacks permission for this resource value: error: type: permission_error code: permission_denied message: You do not have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Servicio no disponible — una dependencia externa no está disponible. content: application/json: examples: service_unavailable: summary: External service unavailable value: error: type: api_error code: service_unavailable message: >- Unable to generate verification code. Please try again later. schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: CreateWebhookRequest: properties: url: type: string maxLength: 2083 minLength: 1 format: uri title: Url description: https endpoint that will receive event POSTs. name: anyOf: - type: string maxLength: 100 - type: 'null' title: Name description: >- Optional human-readable label to identify this webhook in lists/UI. Trimmed server-side; a blank value stores no name. events: anyOf: - items: $ref: '#/components/schemas/WebhookEventName' type: array - type: 'null' title: Events description: Event types to subscribe to (at least one). Preferred over `event`. event: anyOf: - $ref: '#/components/schemas/WebhookEventName' - type: 'null' description: >- Deprecated: a single event type. Use `events`. When set and `events` is omitted, it is saved as a one-element `events` list. deprecated: true type: object required: - url title: CreateWebhookRequest examples: - events: - scribe_session.created - scribe_session.completed - scribe_session.error name: Scribe prod webhook url: https://example.com/webhooks/scribe CreateWebhookResponse: properties: id: type: string title: Id url: type: string title: Url name: anyOf: - type: string - type: 'null' title: Name description: Optional human-readable label, or null if unset. events: items: $ref: '#/components/schemas/WebhookEventName' type: array title: Events event: anyOf: - $ref: '#/components/schemas/WebhookEventName' - type: 'null' description: 'Deprecated: the first subscribed event (events[0]). Use `events`.' deprecated: true isActive: type: boolean title: Isactive signingSecretPrefix: anyOf: - type: string - type: 'null' title: Signingsecretprefix description: >- Display hint for the signing secret (e.g. 'whsec_a1b2c3d4'). The raw secret is only returned at creation/rotation. signingSecretVersion: anyOf: - type: integer - type: 'null' title: Signingsecretversion createdAt: anyOf: - type: string - type: 'null' title: Createdat updatedAt: anyOf: - type: string - type: 'null' title: Updatedat deletedAt: anyOf: - type: string - type: 'null' title: Deletedat signingSecret: type: string title: Signingsecret description: >- Raw HMAC signing secret. Shown once at creation — store it now; it is never retrievable again. Use it to verify the X-Scribe-Api-Signature header. type: object required: - id - url - events - isActive - signingSecret title: CreateWebhookResponse description: Create response — carries the raw signing secret, shown exactly once. ErrorResponse: description: Envoltorio estandarizado de respuesta de error. properties: error: $ref: '#/components/schemas/ErrorDetail' required: - error title: ErrorResponse type: object WebhookEventName: type: string enum: - scribe_session.created - scribe_session.completed - scribe_session.error - scribe_session.updated - scribe_session.cancelled - scribe_session.deleted title: WebhookEventName description: |- Webhook event types exposed to API clients. Mirrors `SynapseWebhookEventType` enum in datalayer (camelCase) but rendered to clients as snake_case dotted strings (closer to Stripe convention and easier to grep in caller logs). ErrorDetail: description: >- Detalle del error con códigos legibles por máquina y mensaje legible por humanos. properties: type: description: Broad error category for high-level handling. examples: - invalid_request_error title: Type type: string code: description: Machine-readable error code. Clients should switch on this value. examples: - parameter_invalid title: Code type: string message: description: Human-readable error message ending with a period. examples: - >- idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code. title: Message type: string param: anyOf: - type: string - type: 'null' default: null description: The request field that caused the error, if applicable. examples: - idCountry title: Param details: anyOf: - additionalProperties: true type: object - type: 'null' default: null description: Optional structured, machine-readable context for the error. examples: - pendingConsultations: - sessionId: abc123 url: https://... title: Details required: - type - code - message title: ErrorDetail type: object securitySchemes: BearerAuth: type: http scheme: bearer description: Clave API enviada como token Bearer ````