¿Qué son los webhooks de OpenAPI y cómo se definen?

¿Qué son los webhooks de OpenAPI y cómo se definen? #

Los webhooks son uno de los patrones más utilizados en las API modernas: permiten que los servicios envíen datos en tiempo real a URL registradas por el cliente, en lugar de obligar a los clientes a consultar periódicamente si hay actualizaciones. Con el lanzamiento de OpenAPI 3.1, la especificación incorporó un mecanismo propio y de primera clase para describir webhooks: el objeto webhooks de nivel superior. Esta incorporación permite a los proveedores de API documentar formalmente los eventos que emiten sus servicios, ofreciendo a los consumidores la misma claridad a nivel de esquema para las cargas útiles de los webhooks entrantes que OpenAPI siempre ha proporcionado para las llamadas salientes a la API.

¿Qué es un webhook? #

Un webhook es un callback HTTP: una solicitud POST que un servidor envía a una URL proporcionada por un cliente cuando ocurre un evento determinado. A diferencia de las llamadas tradicionales a una API REST (en las que el cliente inicia la solicitud), los webhooks invierten el flujo: el servidor es quien envía y el cliente debe exponer un endpoint para recibir la carga útil.

Plataformas como las siguientes utilizan webhooks de forma extensiva:

  • Stripe: para eventos de pagos, suscripciones y fraude.
  • GitHub: para eventos de repositorios, PR y CI/CD.
  • Shopify: para eventos de pedidos, productos y clientes.
  • Twilio: para mensajes entrantes y actualizaciones del estado de las llamadas.
  • SendGrid: para eventos de entrega e interacción con los correos electrónicos.

Sin una forma estandarizada de describir las cargas útiles de los webhooks, los consumidores de las API tenían que basarse en documentación en prosa y confiar en que coincidiera con los eventos que realmente se enviaban en producción.

Webhooks antes de OpenAPI 3.1 #

OpenAPI 3.0 no tenía un concepto nativo de webhook. Los diseñadores de API usaban la característica callbacks para describir las llamadas HTTP salientes desencadenadas por una solicitud concreta a la API, lo que cubría parcialmente los webhooks vinculados a una operación de suscripción. Sin embargo, los webhooks independientes, es decir, los eventos que el servidor dispara de forma asíncrona según cambios en su estado interno, no podían describirse de forma nativa.

Entre las soluciones alternativas se encontraban:

  • Documentar las cargas útiles de los webhooks como componentes de esquema genéricos, sin vinculación con un desencadenador de evento.
  • Usar la extensión x-webhooks (una convención de la comunidad) para adjuntar descripciones de webhooks al documento.
  • Mantener archivos de documentación independientes fuera del documento OpenAPI.

Todos estos enfoques carecían de estandarización y de compatibilidad con las herramientas.

El objeto webhooks en OpenAPI 3.1 #

OpenAPI 3.1 introduce un campo webhooks de nivel superior junto a paths, components e info. Su valor es un mapa de nombres de webhooks a objetos Path Item, la misma estructura que se utiliza para describir los endpoints de una API, lo que permite reutilizar por completo el modelo de operaciones existente de OpenAPI.

openapi: 3.1.0
info:
  title: Order Management API
  version: 1.0.0
webhooks:
  newOrder:
    post:
      summary: New order placed
      description: >
        Sent when a customer successfully places an order. The receiving
        endpoint must respond with HTTP 200 within 5 seconds.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEvent'
      responses:
        "200":
          description: Webhook received successfully
        "400":
          description: Invalid payload

Aquí, newOrder es el nombre del webhook. La operación post describe el método HTTP que el servidor utilizará para enviar el evento, requestBody describe el esquema de la carga útil y responses describe lo que el servidor espera que devuelva el endpoint del cliente.

Reutilización del modelo del objeto Path Item #

Dado que los webhooks de OpenAPI 3.1 usan la misma estructura de objeto Path Item que las rutas de la API, se aplican todas las convenciones existentes de OpenAPI:

  • parameters: describe los parámetros de consulta o de encabezado incluidos en la solicitud del webhook (por ejemplo, un encabezado de firma).
  • requestBody: la carga útil del evento, descrita por completo con esquemas y toda la riqueza de OpenAPI.
  • responses: la respuesta HTTP esperada del endpoint receptor.
  • security: los esquemas de seguridad que se aplican (por ejemplo, un encabezado de firma HMAC para verificar la autenticidad).
  • $ref: las definiciones de webhooks pueden hacer referencia a componentes compartidos, lo que mantiene el documento DRY.

Descripción de varios tipos de eventos #

Una API suele emitir varios tipos de eventos. Cada uno es una entrada independiente en el mapa webhooks:

webhooks:
  orderPlaced:
    post:
      summary: A new order was placed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPlacedEvent'
      responses:
        "200":
          description: OK

  orderShipped:
    post:
      summary: An order was shipped
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderShippedEvent'
      responses:
        "200":
          description: OK

  orderCancelled:
    post:
      summary: An order was cancelled
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCancelledEvent'
      responses:
        "200":
          description: OK

Las propiedades comunes del envoltorio de los eventos (por ejemplo, el tipo de evento, la marca de tiempo y el ID del evento) pueden extraerse a un esquema base y componerse mediante allOf.

Seguridad de los webhooks: descripción de la verificación de firmas #

La mayoría de los proveedores de webhooks firman sus cargas útiles con una firma HMAC enviada en un encabezado de la solicitud (por ejemplo, X-Signature-256). Esto permite a los receptores verificar que el evento procede del remitente legítimo. OpenAPI 3.1 permite documentar este patrón:

webhooks:
  newOrder:
    post:
      parameters:
        - name: X-Signature-256
          in: header
          required: true
          schema:
            type: string
          description: >
            HMAC SHA-256 signature of the request body, computed using your
            webhook signing secret. Verify this before processing the event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEvent'
      responses:
        "200":
          description: OK

Webhooks frente a callbacks en OpenAPI #

Es importante distinguir los webhooks de los callbacks:

  • Los callbacks son llamadas HTTP salientes que realiza el servidor en respuesta a una solicitud concreta a la API; por ejemplo, llamar a una URL que el cliente proporcionó en el cuerpo de la solicitud original. Se definen dentro de un objeto de operación.
  • Los webhooks son eventos autónomos iniciados por el servidor que no están vinculados a ninguna llamada previa a la API. Se definen en el nivel superior del documento.

Ambos mecanismos modelan HTTP de tipo push, pero responden a patrones de integración diferentes.

Compatibilidad de las herramientas con los webhooks #

Varias herramientas de OpenAPI ya admiten el campo webhooks:

  • Redoc: muestra las secciones de webhooks en la documentación generada, distinguiéndolas claramente de las rutas de la API.
  • Stoplight Studio: el editor visual permite añadir y editar webhooks como elementos de primera clase del documento.
  • Redocly CLI: agrupa, valida y aplica linting a documentos que incluyen definiciones de webhooks.
  • openapi-generator: se está trabajando en generar stubs de manejadores de webhooks en el código de servidor generado.
  • Spectral: los conjuntos de reglas personalizados pueden hacer cumplir convenciones en las definiciones de webhooks.

Buenas prácticas para definir webhooks de OpenAPI #

  1. Asigna a cada webhook un nombre claro y orientado al evento: usa nombres como orderPlaced, userCreated o paymentFailed que reflejen el evento del dominio, y no nombres genéricos como webhook1.
  2. Describe por completo el esquema de la carga útil: incluye cada campo con su tipo, descripción y ejemplo. Este es el principal valor de la definición de un webhook para los consumidores.
  3. Documenta la respuesta esperada: especifica qué códigos de estado HTTP espera el servidor y qué ocurre si el cliente no responde a tiempo (por ejemplo, el comportamiento de reintento).
  4. Incluye los encabezados de verificación de firma: describe cualquier encabezado de autenticación o integridad en la sección parameters.
  5. Usa $ref para los componentes de evento compartidos: un esquema común de envoltorio de eventos (con eventId, eventType y timestamp) debe residir en components/schemas y componerse en cada tipo de evento.

Conclusión #

El campo webhooks introducido en OpenAPI 3.1 cubre una carencia de larga data en la especificación, ya que permite a los proveedores de API describir formalmente los eventos asíncronos iniciados por el servidor junto con las operaciones de su API REST. Al reutilizar el conocido modelo del objeto Path Item, los webhooks se benefician de todo el poder expresivo de los esquemas, parámetros y definiciones de seguridad de OpenAPI. Para los equipos que crean integraciones basadas en eventos, desde plataformas de pago hasta comercio electrónico o IoT, la documentación estandarizada de los webhooks reduce las conjeturas durante la integración y mejora la experiencia de desarrollo de los consumidores de las API.

Última actualización: 29 de abril de 2026.

Este sitio web no está afiliado a la OpenAPI Initiative.