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

# Crear webhook

> Registra un endpoint https al que se entregarán los eventos suscritos. La respuesta incluye `secret_key` (para verificar la firma HMAC de cada entrega) UNA SOLA VEZ — guárdala: ninguna consulta posterior la devuelve.



## OpenAPI

````yaml /openapi.json post /webhooks
openapi: 3.1.0
info:
  description: API de timbrado CFDI 4.0 de Palenca.
  title: Ipsofactura API
  version: v1
servers:
  - description: Producción
    url: https://api.ipsofactura.com
  - description: Sandbox (pruebas, sin validez fiscal)
    url: https://sandbox.api.ipsofactura.com
security:
  - apiKeyAuth: []
tags:
  - description: Timbrado, complemento de pago, cancelación y descarga de CFDIs.
    name: CFDI
  - description: Alta y consulta de empresas emisoras.
    name: Empresas
  - description: Administración del Certificado de Sello Digital (CSD).
    name: Certificados
  - description: >-
      Suscripciones de webhooks: notificaciones de timbrado, cancelación y
      pagos.
    name: Webhooks
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Crear webhook
      description: >-
        Registra un endpoint https al que se entregarán los eventos suscritos.
        La respuesta incluye `secret_key` (para verificar la firma HMAC de cada
        entrega) UNA SOLA VEZ — guárdala: ninguna consulta posterior la
        devuelve.
      operationId: create
      requestBody:
        content:
          application/json:
            example:
              description: Notificaciones de timbrado
              events:
                - cfdi.timbrado
                - cfdi.cancelado
              url: https://api.ejemplo.com/webhooks/ipsofactura
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
        required: true
      responses:
        '201':
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/WebhookCreatedResponse'
          description: Webhook creado; secret_key visible solo en esta respuesta
        '400':
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/WebhookCreatedResponse'
          description: >-
            URL no https / host privado, evento desconocido o límite de webhooks
            alcanzado
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            API key faltante o inválida (AUTHENTICATION_REQUIRED /
            INVALID_API_KEY)
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            La cuenta está suspendida (ACCOUNT_SUSPENDED). Un recurso de otra
            cuenta NO responde 403: responde 404, igual que uno que no existe.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Límite de requests por minuto excedido (RATE_LIMIT_EXCEEDED). Ver
            headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
            y Retry-After.
components:
  schemas:
    CreateWebhookRequest:
      properties:
        companyId:
          format: uuid
          type: string
        description:
          maxLength: 255
          minLength: 0
          type: string
        events:
          items:
            type: string
          minItems: 1
          type: array
        url:
          maxLength: 255
          minLength: 0
          type: string
      required:
        - events
        - url
      type: object
    WebhookCreatedResponse:
      properties:
        active:
          type: boolean
        companyId:
          format: uuid
          type: string
        description:
          type: string
        events:
          items:
            type: string
          type: array
        id:
          format: uuid
          type: string
        secretKey:
          type: string
        secretKeyPrefix:
          type: string
        url:
          type: string
        version:
          type: string
      type: object
    ErrorResponse:
      properties:
        code:
          description: >-
            Código de error de ipsofactura. Estable y cerrado (catálogo
            ErrorCode), pero deliberadamente grueso: TODO rechazo de validación
            del SAT llega como VALIDATION_ERROR. Úsalo para decidir el flujo
            general (reintentar, autenticar de nuevo, corregir el comprobante).
          example: VALIDATION_ERROR
          type: string
        id:
          type: string
        idempotencyKey:
          type: string
        message:
          description: >-
            Descripción legible del error, en texto libre. NO la parsees: cuando
            el rechazo viene del SAT, este texto lo redacta el PAC, cambia entre
            proveedores y puede cambiar sin previo aviso. Para ramificar por
            regla del SAT usa sat_code; para ramificar por tipo de error usa
            code. El mensaje es para mostrarlo o registrarlo.
          example: >-
            CFDI40147: El RFC del receptor no se encuentra en la lista de
            contribuyentes inscritos no cancelados del SAT
          type: string
        retryAfter:
          format: int32
          type: integer
        sat_code:
          description: >-
            Código de validación del SAT (CFDIxxxxx) del rechazo. Presente SÓLO
            cuando el comprobante fue rechazado por el SAT a través de un PAC;
            ausente en errores propios de ipsofactura (validación local,
            autenticación, rate limit, servicio no disponible). Es específico
            donde `code` es genérico: `code` te dice que hubo un rechazo de
            validación, `sat_code` te dice cuál regla se incumplió. También se
            omite si el PAC no devolvió ningún código: nunca se inventa uno.
          example: CFDI40147
          type: string
  securitySchemes:
    apiKeyAuth:
      description: API key emitida por Ipsofactura, enviada en el header x-api.
      in: header
      name: x-api
      type: apiKey

````