Webhook은 LangSmith 애플리케이션에서 외부 서비스로의 이벤트 기반 통신을 가능하게 합니다. 예를 들어, LangSmith에 대한 API 호출이 실행을 완료한 후 별도의 서비스에 업데이트를 발행할 수 있습니다. 많은 LangSmith endpoint는 webhook 파라미터를 허용합니다. POST 요청을 수락할 수 있는 endpoint에서 이 파라미터가 지정되면, LangSmith는 run이 완료될 때 요청을 전송합니다. LangSmith로 작업할 때, API 호출이 완료된 후 업데이트를 받기 위해 webhook을 사용할 수 있습니다. Webhook은 run이 처리를 완료한 후 서비스에서 작업을 트리거하는 데 유용합니다. 이를 구현하려면 POST 요청을 수락할 수 있는 endpoint를 노출하고 API 요청에서 이 endpoint를 webhook 파라미터로 전달해야 합니다. 현재 SDK는 webhook endpoint 정의를 위한 내장 지원을 제공하지 않지만, API 요청을 사용하여 수동으로 지정할 수 있습니다.

​
지원되는 endpoint

다음 API endpoint는 webhook 파라미터를 허용합니다:
OperationHTTP MethodEndpoint
Create RunPOST/thread/{thread_id}/runs
Create Thread CronPOST/thread/{thread_id}/runs/crons
Stream RunPOST/thread/{thread_id}/runs/stream
Wait RunPOST/thread/{thread_id}/runs/wait
Create CronPOST/runs/crons
Stream Run StatelessPOST/runs/stream
Wait Run StatelessPOST/runs/wait
이 가이드에서는 run을 스트리밍한 후 webhook을 트리거하는 방법을 보여줍니다.

​
Assistant와 thread 설정하기

API 호출을 하기 전에 assistant와 thread를 설정하세요.
  • Python
  • JavaScript
  • CURL
from langgraph_sdk import get_client

client = get_client(url=<DEPLOYMENT_URL>)
assistant_id = "agent"
thread = await client.threads.create()
print(thread)
응답 예시: 
{
    "thread_id": "9dde5490-2b67-47c8-aa14-4bfec88af217",
    "created_at": "2024-08-30T23:07:38.242730+00:00",
    "updated_at": "2024-08-30T23:07:38.242730+00:00",
    "metadata": {},
    "status": "idle",
    "config": {},
    "values": null
}

​
Graph run에서 webhook 사용하기

Webhook을 사용하려면 API 요청에서 webhook 파라미터를 지정하세요. Run이 완료되면 LangSmith는 지정된 webhook URL로 POST 요청을 전송합니다. 예를 들어, 서버가 https://my-server.app/my-webhook-endpoint에서 webhook 이벤트를 수신하는 경우, 요청에 다음을 포함하세요:
  • Python
  • JavaScript
  • CURL
input = { "messages": [{ "role": "user", "content": "Hello!" }] }

async for chunk in client.runs.stream(
    thread_id=thread["thread_id"],
    assistant_id=assistant_id,
    input=input,
    stream_mode="events",
    webhook="https://my-server.app/my-webhook-endpoint"
):
    pass

​
Webhook payload

LangSmith는 Run 형식으로 webhook 알림을 전송합니다. 자세한 내용은 API Reference를 참조하세요. 요청 payload에는 kwargs 필드에 run input, configuration 및 기타 metadata가 포함됩니다.

​
Webhook 보안

승인된 요청만 webhook endpoint에 도달하도록 하려면 query parameter로 보안 토큰을 추가하는 것을 고려하세요: 
https://my-server.app/my-webhook-endpoint?token=YOUR_SECRET_TOKEN
서버는 요청을 처리하기 전에 이 토큰을 추출하고 검증해야 합니다.

​
Webhook 비활성화

langgraph-api>=0.2.78부터 개발자는 langgraph.json 파일에서 webhook을 비활성화할 수 있습니다: 
{
  "http": {
    "disable_webhooks": true
  }
}
이 기능은 주로 self-hosted 배포를 위한 것으로, 플랫폼 관리자나 개발자가 방화벽 규칙이나 기타 네트워크 제어를 구성하지 않는 경우 보안 태세를 단순화하기 위해 webhook을 비활성화하는 것을 선호할 수 있습니다. Webhook을 비활성화하면 신뢰할 수 없는 payload가 내부 endpoint로 전송되는 것을 방지하는 데 도움이 됩니다. 전체 구성 세부 정보는 configuration file reference를 참조하세요.

​
Webhook 테스트

다음과 같은 온라인 서비스를 사용하여 webhook을 테스트할 수 있습니다:
  • Beeceptor – 테스트 endpoint를 빠르게 생성하고 들어오는 webhook payload를 검사합니다.
  • Webhook.site – 실시간으로 들어오는 webhook 요청을 보고, 디버그하고, 로그를 기록합니다.
이러한 도구는 LangSmith가 서비스로 webhook을 올바르게 트리거하고 전송하는지 확인하는 데 도움이 됩니다.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I