OpenAPI 웹훅
OpenAPI 웹훅 (OpenAPI Webhooks)
API 사용자에게 "여러분 앱이 어떤 데이터와 함께 그들의 앱에 요청을 보낼 수 있어요"라고 알리고 싶은 경우가 있어요. 보통 어떤 이벤트를 알려주기 위해서죠.
즉, 원래처럼 사용자들이 여러분 API에 요청을 보내는 게 아니라, 여러분 API(혹은 앱)가 그들의 시스템(그들의 API, 그들의 앱)에 요청을 보낼 수 있는 구조예요.
이걸 보통 웹훅(webhook) 이라고 부릅니다.
출처: 공식문서
웹훅의 흐름
보통의 과정은 이래요. 여러분이 코드에서 보낼 메시지, 즉 요청의 body를 정의합니다.
그리고 어떤 시점에 여러분 앱이 그 요청·이벤트를 보낼지도 어떤 방식으로 정의해요.
사용자들은 (예를 들어 어딘가의 웹 대시보드에서) 여러분 앱이 그 요청을 보내야 할 URL을 어떤 방식으로 정의합니다.
웹훅 URL을 등록하는 로직과 실제로 요청을 보내는 코드는 전부 여러분 몫이에요. 여러분 자신의 코드에서 원하는 대로 작성하면 됩니다.
FastAPI와 OpenAPI로 웹훅 문서화하기
FastAPI에서는 OpenAPI를 이용해 이런 웹훅들의 이름, 여러분 앱이 보낼 수 있는 HTTP 동작의 종류(POST, PUT 등), 그리고 여러분 앱이 보낼 요청 body들을 정의할 수 있어요.
이렇게 하면 사용자들이 여러분 웹훅 요청을 받을 API를 구현하기가 훨씬 쉬워져요. 심지어 그들 자신의 API 코드 일부를 자동 생성할 수도 있게 됩니다.
참고: 웹훅은 OpenAPI 3.1.0 이상에서 사용할 수 있고, FastAPI
0.99.0이상에서 지원해요.
웹훅이 있는 앱
FastAPI 앱을 만들면 webhooks 속성이 있는데, 이걸로 _path operation_을 정의하듯 웹훅을 정의할 수 있어요. 예를 들어 @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"]
여러분이 정의한 웹훅은 OpenAPI 스키마와 자동 docs UI에 포함됩니다.
참고:
app.webhooks객체는 사실 그냥APIRouter예요. 앱을 여러 파일로 구조화할 때 쓰는 그 타입과 동일하죠.웹훅에서는 실제로 path(
/items/같은)를 선언하지 않는다는 점에 유의하세요. 거기에 전달하는 텍스트는 그저 웹훅의 식별자(이벤트의 이름)예요. 예를 들어@app.webhooks.post("new-subscription")에서 웹훅 이름은new-subscription입니다.그 이유는 사용자들이 웹훅 요청을 받을 실제 URL path를 다른 방식(예: 웹 대시보드)으로 정의할 거라고 기대하기 때문이에요.
문서 확인하기
이제 앱을 실행하고 http://127.0.0.1:8000/docs로 가 볼게요.
문서에 일반적인 _path operations_이 있고 이제 웹훅도 함께 있는 걸 볼 수 있어요.