Webhooks de OpenAPI¶

Hay casos en los que quieres decirle a los usuarios de tu API que tu aplicación podría llamar a la aplicación de ellos (enviando una petición) con algunos datos, normalmente para notificar sobre algún tipo de evento.

Esto significa que en lugar del proceso normal de tus usuarios enviando peticiones a tu API, es tu API (o tu aplicación) la que podría enviar peticiones a su sistema (a su API, a su aplicación).

Esto normalmente se llama webhook.

Pasos de los webhooks¶

El proceso normalmente es que tú defines en tu código cuál es el mensaje que enviarás, el cuerpo de la petición.

También defines de alguna manera en qué momentos tu aplicación enviará esas peticiones o eventos.

Y tus usuarios definen de alguna manera (por ejemplo en un panel web en algún lugar) la URL donde tu aplicación debería enviar esas peticiones.

Toda la lógica sobre cómo registrar las URLs para los webhooks y el código para realmente enviar esas peticiones depende de ti. Lo escribes como quieras en tu propio código.

Documentando webhooks con FastAPI y OpenAPI¶

Con FastAPI, usando OpenAPI, puedes definir los nombres de estos webhooks, los tipos de operaciones HTTP que tu aplicación puede enviar (por ejemplo POST, PUT, etc.) y los cuerpos de las peticiones que tu aplicación enviaría.

Esto puede hacer mucho más fácil para tus usuarios implementar sus APIs para recibir tus peticiones de webhook, incluso podrían ser capaces de autogenerar parte de su propio código de API.

Una aplicación con webhooks¶

Cuando creas una aplicación FastAPI, hay un atributo webhooks que puedes usar para definir webhooks, de la misma manera que definirías operaciones de ruta, por ejemplo con @app.webhooks.post().

from datetime import datetime

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Subscription(BaseModel):
    username: str
    monthly_fee: float
    start_date: datetime


@app.webhooks.post("new-subscription")
def new_subscription(body: Subscription):
    """
    When a new user subscribes to your service we'll send you a POST request with this
    data to the URL that you register for the event `new-subscription` in the dashboard.
    """


@app.get("/users/")
def read_users():
    return ["Rick", "Morty"]

Los webhooks que definas terminarán en el esquema de OpenAPI y en la interfaz de documentación automática.

Ten en cuenta que con los webhooks en realidad no estás declarando una ruta (como /items/), el texto que pasas ahí es simplemente un identificador del webhook (el nombre del evento), por ejemplo en @app.webhooks.post("new-subscription"), el nombre del webhook es new-subscription.

Esto se debe a que se espera que tus usuarios definan la ruta URL real donde quieren recibir la petición del webhook de alguna otra manera (por ejemplo, un panel web).

Revisar la documentación¶

Ahora puedes iniciar tu app e ir a http://127.0.0.1:8000/docs.

Verás que tu documentación tiene las operaciones de ruta normales y ahora también algunos webhooks: