Webhook 과 Async Event

대부분의 API 는 당겨오는 모양이야. Client 가 묻고 server 가 답해. Webhook 은 그 방향을 뒤집어. 무슨 일이 생기면 server 가 client 가 등록해둔 URL 로 event 를 밀어줘. 만든 쪽에서 벌어진 일에 쓰는 쪽이 빨리 반응해야 할 때 맞는 답이야 — 결제 확인, build 완료, 메시지 도착 같은 것들.

OpenAPI 3.1 은 webhook 을 spec 의 어엿한 시민으로 올렸어. 문서 하나가 요청/응답 API 와 그 API 가 밀어줄 event 를 둘 다 설명하는 거지. Webhook 을 받는 서비스도 문서 하나로 다 설명되고, MCP server 가 그걸 받아다 쓸 수 있어 — 검증하고, 모양을 다듬고, resource 나 알림으로 다시 내놓는 식으로.

MCP 도 이제 비동기 이야기를 갖게 됐어. 2025-11-25 revision 이 async task 확장을 들여왔거든. Tool call 이 결과를 기다리는 대신 task 손잡이를 돌려줄 수 있어 (working, input_required, completed, failed, cancelled). Client 는 그걸 주기적으로 확인하거나, task 가 끝나면 알림을 받아. MCP 안에서 '지금 부르고 나중에 받아가기' 를 하는 셈이야. Webhook 과 모양은 같은데, 별도 URL 대신 protocol 의 언어로 한다는 게 달라.

고르는 기준은 이래. Event 의 진짜 주인이 만든 쪽이고 쓰는 쪽이 마침 HTTP 로 닿을 수 있다면 webhook 이 맞아. 쓰는 쪽이 protocol 을 통해 오래 걸리는 작업을 시작하고 결과만 나중에 받으면 된다면 MCP async task 가 맞고. 둘은 경쟁 관계가 아니야. '이거 시간 걸리니까 나중에 다시 알려줄게' 를 다른 손맛으로 구현한 것뿐이지.

Code

Webhook 받기 — 최소 FastAPI 모양·python

@app.post("/hooks/stripe")
async def stripe_hook(request: Request):
    payload = await request.body()
    sig = request.headers.get("Stripe-Signature")
    event = stripe.Webhook.construct_event(payload, sig, WH_SECRET)
    if event["type"] == "payment_intent.succeeded":
        await record_payment(event["data"]["object"])
    return {"received": True}

MCP async-task lifecycle·json

// 초기 tool call 이 task handle 반환
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"build_codebase",...}}
// → result: {"taskId":"task_42","state":"working"}

// Client 가 poll (또는 push notification 받음)
{"jsonrpc":"2.0","id":2,"method":"tasks/get","params":{"taskId":"task_42"}}
// → result: {"taskId":"task_42","state":"working","progress":0.6}
// 나중에 → result: {"taskId":"task_42","state":"completed","value":{...}}

Exercise

네가 붙여 쓰는 외부 서비스를 하나 골라 (Stripe, GitHub, Linear 같은 거). 그 capability 중에 어떤 게 당겨오는 모양이고, 어떤 게 미는 모양 (webhook) 이고, 어떤 게 MCP async task 로 덕을 볼지 구분해봐. 대개 뒤섞여 있어서 놀라게 돼. 딱 떨어지는 경우가 오히려 드물어.

Code

External links

Exercise

Progress

댓글 0