> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tupana.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear webhook

> Crea un nuevo webhook para una entidad específica del usuario autenticado.

Crea un nuevo webhook para recibir notificaciones automáticas cuando ocurren eventos relacionados con documentos. El webhook se asocia con una entidad específica del usuario autenticado.

## ¿Para qué se usa?

Crea un nuevo webhook para recibir notificaciones automáticas cuando ocurren eventos relacionados con documentos. Útil para:

* Configurar notificaciones automáticas cuando se emiten documentos
* Recibir alertas cuando documentos son aceptados o rechazados por el SII
* Integrar con sistemas externos para procesamiento automático de documentos
* Monitorear el estado de entrega de documentos importantes

## Qué hace

* Crea un nuevo webhook asociado a una entidad específica
* Configura la URL de callback que recibirá las notificaciones
* Define los eventos específicos que se notificarán (emitido, entregado, rechazado, pagado, cancelado)
* Permite configurar una clave secreta para verificar la autenticidad de las notificaciones
* Establece el estado inicial del webhook (activo o inactivo)

## Ejemplos de uso

* **Notificaciones de emisión:** Configurar un webhook para recibir notificaciones cada vez que se emite un documento
* **Integración con ERP:** Conectar el sistema con un ERP externo para procesar documentos automáticamente
* **Alertas de rechazo:** Recibir notificaciones inmediatas cuando el SII rechaza un documento

## Consideraciones Importantes

### Entidad maestra

Debes especificar el `master_entity_id` de la entidad para la cual quieres crear el webhook. El usuario debe tener acceso a la entidad especificada.

### Validación de URL

No puede existir un webhook con la misma URL para la misma entidad. Si intentas crear un webhook duplicado, recibirás un error de validación.

### Eventos disponibles

* `document.issued` - Documento emitido exitosamente
* `document.delivered` - Documento entregado al receptor
* `document.rejected` - Documento rechazado por el SII
* `document.paid` - Documento pagado
* `document.unpaid` - Documento revertido de pagado a no pagado
* `document.cancelled` - Documento cancelado


## OpenAPI

````yaml POST /webhooks
openapi: 3.0.0
info:
  title: Tupana API
  description: API para integración con el sistema Tupana - Facturación Electrónica
  version: 1.0.0
servers:
  - url: https://api.tupana.ai/v1
    description: Servidor de producción
security:
  - apiKeyAuth: []
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Crear webhook
      description: >-
        Crea un nuevo webhook para una entidad específica del usuario
        autenticado.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
            example:
              master_entity_id: 123
              url: https://mi-sistema.com/webhook/callback
              events:
                - document.issued
                - document.delivered
                - document.rejected
              secret: mi-clave-secreta-super-segura
              is_active: true
      responses:
        '201':
          description: Webhook creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: 1
                url: https://mi-sistema.com/webhook/callback
                events:
                  - document.issued
                  - document.delivered
                  - document.rejected
                events_display:
                  - Emitido
                  - Entregado
                  - Rechazado SII
                secret: mi-clave-secreta-super-segura
                is_active: true
                last_status_code: null
                last_sent_at: null
                success_rate: 0
                last_delivery: null
                created_at: '2025-01-13T11:00:00Z'
                updated_at: '2025-01-13T11:00:00Z'
        '400':
          description: Datos inválidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Usuario no autenticado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Usuario sin acceso a entidades
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    WebhookCreate:
      type: object
      required:
        - master_entity_id
        - url
        - events
      properties:
        master_entity_id:
          type: integer
          description: ID de la entidad maestra para la cual se crea el webhook
          example: 123
        url:
          type: string
          format: uri
          description: URL del endpoint que recibirá las notificaciones
        events:
          type: array
          description: Lista de eventos a notificar
          items:
            type: string
            enum:
              - document.issued
              - document.delivered
              - document.rejected
              - document.paid
              - document.unpaid
              - document.cancelled
          minItems: 1
        secret:
          type: string
          description: Clave secreta para verificar la autenticidad de las notificaciones
          maxLength: 255
        is_active:
          type: boolean
          description: Si el webhook está activo
          default: true
    Webhook:
      type: object
      properties:
        id:
          type: integer
          description: ID único del webhook
        url:
          type: string
          format: uri
          description: URL del endpoint que recibe las notificaciones
        events:
          type: array
          description: Lista de eventos configurados
          items:
            type: string
            enum:
              - document.issued
              - document.delivered
              - document.rejected
              - document.paid
              - document.unpaid
              - document.cancelled
        events_display:
          type: array
          description: Nombres legibles de los eventos
          items:
            type: string
          example:
            - Emitido
            - Entregado
            - Rechazado SII
        secret:
          type: string
          description: Clave secreta para verificar notificaciones
          nullable: true
        is_active:
          type: boolean
          description: Si el webhook está activo
        last_status_code:
          type: integer
          description: Último código HTTP de respuesta
          nullable: true
        last_sent_at:
          type: string
          format: date-time
          description: Fecha de último envío
          nullable: true
        success_rate:
          type: number
          format: float
          description: Tasa de éxito de entregas (0-100)
          minimum: 0
          maximum: 100
        last_delivery:
          type: object
          description: Información de la última entrega
          nullable: true
          properties:
            id:
              type: integer
              description: ID de la entrega
            event:
              type: string
              description: Evento de la entrega
            is_success:
              type: boolean
              description: Si la entrega fue exitosa
            status_code:
              type: integer
              description: Código HTTP de respuesta
            sent_at:
              type: string
              format: date-time
              description: Fecha y hora del envío
            document_id:
              type: integer
              description: ID del documento
        created_at:
          type: string
          format: date-time
          description: Fecha de creación
        updated_at:
          type: string
          format: date-time
          description: Fecha de última actualización
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: string
          description: Código de error
          example: VALIDATION_ERROR
          enum:
            - VALIDATION_ERROR
            - AUTHENTICATION_ERROR
            - AUTHORIZATION_ERROR
            - NOT_FOUND
            - SII_ERROR
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensaje de error
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API Key para autenticación. Debe proporcionarse en el header
        Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo
        'Api-Key ' seguido de tu API key)

````