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

# Actualizar webhook

> Modifica uno o más campos del webhook. Es la forma de subir un webhook creado antes de octubre 2026 al contrato de ids públicos: `{"api_version": 2}`.

Modifica uno o más campos del webhook: `url`, `events`, `secret`, `is_active`, `environment` o `api_version`.

Es la forma de subir un webhook creado antes de octubre de 2026 al contrato de ids públicos:

```json theme={null}
{ "api_version": 2 }
```

Desde ese momento `data.id`, `sender.id` y `receiver.id` llegan como `docu_…` y `ment_…`. Ver [Identificadores en el payload](/user-guide/webhooks#identificadores-en-el-payload).


## OpenAPI

````yaml api-reference/openapi-v2.json PATCH /webhooks/{webhook_id}/
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/{webhook_id}/:
    patch:
      tags:
        - Webhooks
      summary: Actualizar webhook
      description: >-
        Modifica uno o más campos del webhook. Es la forma de subir un webhook
        creado antes de octubre 2026 al contrato de ids públicos:
        `{"api_version": 2}`.
      operationId: updateWebhook_v2
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: public_id del webhook (`dowe_…`)
          schema:
            type: string
          example: dowe_2c9e5a1b7f3d0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
            example:
              api_version: 2
      responses:
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Datos inválidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No autenticado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    WebhookUpdate:
      type: object
      description: Campos editables de un webhook. Todos opcionales (PATCH).
      properties:
        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.