> ## 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.

### Ambiente (`environment`)

`both` (default) recibe los documentos de producción y de sandbox; `production` o `sandbox` los separan sobre la misma empresa. Los eventos que no son de documento (credenciales, folios, cobros, programados) se entregan como producción.

### Formato de identificadores (`api_version`)

`2`: todos los ids del payload son públicos (`docu_…`, `ment_…`), igual que la API v2. `1`: ids enteros, el contrato de la API v1. Si lo omites, el default sigue la ruta: `/v2/webhooks/` crea en 2 y `/v1/webhooks/` crea en 1. Ver [Identificadores en el payload](/user-guide/webhooks#identificadores-en-el-payload).

### 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
* `folio_request.completed` - Timbraje listo: el CAF se puede retirar
* `folio_request.failed` - El SII no autorizó folios; no se consumió nada
* `folio_request.authorized_without_caf` - El SII autorizó un rango y no entregó el archivo
* `document.unpaid` - Documento revertido de pagado a no pagado
* `document.cancelled` - Documento cancelado


## OpenAPI

````yaml api-reference/openapi-v2.json POST /webhooks/
openapi: 3.0.0
info:
  title: Tupana API — v2
  description: >-
    API v2 de Tupana: facturación electrónica, cesiones, recaudación, consultas,
    boleta de honorarios y nómina. Los identificadores de recursos son public
    IDs opacos con prefijo (docu_, ment_, cred_, doce_, empl_…).
  version: 2.0.0
servers:
  - url: https://api.tupana.ai/v2
    description: Producción (v2)
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_v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
            example:
              master_entity_id: ment_4829301923847
              url: https://mi-sistema.com/webhook/callback
              events:
                - document.issued
                - document.delivered
                - document.rejected
              secret: mi-clave-secreta-super-segura
              is_active: true
              environment: production
              api_version: 2
      responses:
        '201':
          description: Webhook creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: dowe_2c9e5a1b7f3d0
                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'
                environment: production
                api_version: 2
        '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: string
          description: ID de la entidad maestra para la cual se crea el webhook
          example: ment_4829301923847
        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.trace_updated
              - 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
        environment:
          type: string
          enum:
            - both
            - production
            - sandbox
          default: both
          description: >-
            De qué ambiente recibe eventos de documentos: `both` (default),
            `production` o `sandbox`. Los eventos que no son de documento
            (credenciales, folios, cobros, programados) se entregan como
            producción.
        api_version:
          type: integer
          enum:
            - 1
            - 2
          default: 2
          description: >-
            Formato de los identificadores que viajan en el payload. `2`: todos
            los ids son public_id (`docu_…` documento, `ment_…` emisor/receptor,
            `scdo_…` programado, `fir_…` solicitud de folios, `dowe_…` webhook).
            `1`: ids enteros, el contrato de la API v1. Si se omite, el default
            sigue la ruta de creación: `/v2/webhooks/` crea en 2 y
            `/v1/webhooks/` crea en 1 (desde la plataforma, la versión que ya
            usa la empresa). Los webhooks creados antes de octubre 2026 quedaron
            en `1`: súbelos con PATCH o desde la plataforma.
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: ID único del webhook
          example: dowe_2c9e5a1b7f3d0
        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.trace_updated
              - 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: string
              description: ID de la entrega
              example: wede_5f1c2a9b7d3e0
            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
        environment:
          type: string
          enum:
            - both
            - production
            - sandbox
          description: >-
            De qué ambiente recibe eventos de documentos: `both` (default),
            `production` o `sandbox`. Los eventos que no son de documento
            (credenciales, folios, cobros, programados) se entregan como
            producción.
        api_version:
          type: integer
          enum:
            - 1
            - 2
          description: >-
            Formato de los identificadores que viajan en el payload. `2`: todos
            los ids son public_id (`docu_…` documento, `ment_…` emisor/receptor,
            `scdo_…` programado, `fir_…` solicitud de folios, `dowe_…` webhook).
            `1`: ids enteros, el contrato de la API v1. Si se omite, el default
            sigue la ruta de creación: `/v2/webhooks/` crea en 2 y
            `/v1/webhooks/` crea en 1 (desde la plataforma, la versión que ya
            usa la empresa). Los webhooks creados antes de octubre 2026 quedaron
            en `1`: súbelos con PATCH o desde la plataforma.
    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)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.