[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M792FSVME49S8DJT82NRDFWY":3,"skill-same:01M792FSVME49S8DJT82NRDFWY":62},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":39,"commitSha":40,"skillDirectory":41,"forksCount":42,"repositoryHtmlUrl":43,"repositoryHomepageUrl":6,"ownerHtmlUrl":44,"ownerBlogUrl":45,"ownerDescription":46,"updatedAt":47,"install":48,"resources":61},"01M792FSVME49S8DJT82NRDFWY","langchain-webhooks-events",null,"Dispatch LangChain 1.0 chain\u002Fagent events to external systems — webhooks, Kafka,\nRedis Streams, SNS — via async fire-and-forget callbacks, subgraph-aware wiring,\nand HMAC-signed delivery with idempotency keys. Use when firing webhooks on tool\ncalls, pushing telemetry to Kafka \u002F Redis Streams, or fanning progress to multiple\nsubscribers without blocking the chain.\nTrigger with \"langchain webhook\", \"langchain event dispatch\", \"langchain callback kafka\",\n\"langchain pubsub\", \"langchain per-tool webhook\", \"BaseCallbackHandler webhook\",\n\"on_tool_end webhook\", \"langchain analytics event\".","jukeyman\u002Fjukeyman-skills","jukeyman","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F142960420?v=4","01M78FR4Y3DHMMCBCC0GXXNB3F","RICK JEFFERSON","01M78FR4Z8RVQRAD31Y5J7V6EB",1,"MIT","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsaas-packs--langchain-py-pack--langchain-webhooks-events\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: langchain-webhooks-events\ndescription: |\n  Dispatch LangChain 1.0 chain\u002Fagent events to external systems — webhooks, Kafka,\n  Redis Streams, SNS — via async fire-and-forget callbacks, subgraph-aware wiring,\n  and HMAC-signed delivery with idempotency keys. Use when firing webhooks on tool\n  calls, pushing telemetry to Kafka \u002F Redis Streams, or fanning progress to multiple\n  subscribers without blocking the chain.\n  Trigger with \"langchain webhook\", \"langchain event dispatch\", \"langchain callback kafka\",\n  \"langchain pubsub\", \"langchain per-tool webhook\", \"BaseCallbackHandler webhook\",\n  \"on_tool_end webhook\", \"langchain analytics event\".\nallowed-tools: Read, Write, Edit, Bash(python:*)\nversion: 2.0.0\nlicense: MIT\nauthor: Jeremy Longshore \u003Cjeremy@intentsolutions.io>\ntags: [saas, langchain, langgraph, python, langchain-1.0, webhooks, async, events, callbacks]\ncompatible-with: claude-code, codex\n---\n\n# LangChain Webhooks and Event Dispatch (Python)\n\n## Overview\n\nA team wires per-tool webhook dispatch from their LangChain agent via FastAPI\n`BackgroundTasks` — analytics is always N seconds late because `BackgroundTasks`\nfire **after** the HTTP response closes, not during the stream (P60). Worse:\nthe `BaseCallbackHandler` they attached via `.with_config(callbacks=[h])`\nfires on the outer agent but is dark on the subagent's tool calls — custom\ncallbacks are **not** inherited by LangGraph subgraphs (P28), they must be\npassed via `config[\"callbacks\"]` at invoke time.\n\nPain-catalog anchors handled here:\n\n- P28 — Callbacks via `with_config` don't propagate to subgraphs\n- P46 — SSE streams dropped by buffering proxies (see `langchain-langgraph-streaming`)\n- P47 — `astream_events(v2)` emits thousands of events; never forward raw\n- P48 — Sync `invoke()` inside async endpoint blocks the event loop\n- P60 — `BackgroundTasks` fire post-response; wrong for per-event dispatch\n\nThis skill walks through an async `AsyncCallbackHandler` with fire-and-forget\ndispatch, per-target sinks for HTTP \u002F Kafka \u002F Redis Streams \u002F SNS, HMAC-signed\ndelivery with 1s\u002F5s\u002F30s retry and DLQ, idempotency keys = `run_id + event_type\n+ step_index`, and `config[\"callbacks\"]` wiring that makes subagent calls visible.\nTypical webhook latency budget: \u003C500ms per event. Pin: `langchain-core 1.0.x`,\n`langgraph 1.0.x`. Scope: server-to-server dispatch only — UI streaming is in\n`langchain-langgraph-streaming`.\n\n## Prerequisites\n\n- Python 3.10+\n- `langchain-core >= 1.0, \u003C 2.0`, `langgraph >= 1.0, \u003C 2.0`\n- `httpx >= 0.27` for async HTTP (or `aiohttp`)\n- One of: `aiokafka`, `redis[hiredis] >= 5`, `aioboto3` (per target)\n- An event sink — a webhook endpoint, Kafka topic, Redis Stream, or SNS topic\n- A shared secret (for HMAC) stored in your secret manager, not env\n\n## Instructions\n\n### Step 1 — Write an async handler that fire-and-forget dispatches\n\nSync dispatch from a callback blocks the chain — a slow HTTP POST during\n`on_tool_end` serializes all downstream tokens behind it (P48). Use\n`asyncio.create_task(...)` so the dispatch runs alongside the chain:\n\n```python\nimport asyncio\nimport uuid\nfrom typing import Any\nfrom langchain_core.callbacks import AsyncCallbackHandler\n\nclass EventDispatchHandler(AsyncCallbackHandler):\n    \"\"\"Fire-and-forget dispatch to external sinks.\n\n    IMPORTANT: subclass AsyncCallbackHandler (not BaseCallbackHandler) so\n    on_* methods are awaited. Mixing sync and async handlers is a silent\n    footgun — sync on_* blocks the event loop (P48).\n    \"\"\"\n\n    def __init__(self, sink, *, run_id: str | None = None):\n        self.sink = sink                      # dispatch target — Step 3\n        self.run_id = run_id or str(uuid.uuid4())\n        self._tasks: set[asyncio.Task] = set()\n\n    def _dispatch(self, event_type: str, payload: dict, step_index: int) -> None:\n        # Fire-and-forget. Keep a strong reference so the task isn't GC'd\n        # mid-flight (asyncio quirk — orphan tasks get garbage-collected).\n        task = asyncio.create_task(\n            self.sink.send(\n                idempotency_key=f\"{self.run_id}:{event_type}:{step_index}\",\n                event_type=event_type,\n                payload=payload,\n            )\n        )\n        self._tasks.add(task)\n        task.add_done_callback(self._tasks.discard)\n\n    async def on_tool_end(self, output: Any, *, run_id, parent_run_id=None, **kwargs):\n        # 4000 char cap — keep payload under typical webhook body limits\n        # while preserving enough context for downstream analytics.\n        MAX_OUTPUT_CHARS = 4000\n        self._dispatch(\n            \"tool_end\",\n            {\"output\": str(output)[:MAX_OUTPUT_CHARS], \"run_id\": str(run_id)},\n            step_index=kwargs.get(\"tags\", []).__len__() or 0,\n        )\n\n    async def on_chain_end(self, outputs: dict, *, run_id, **kwargs):\n        # Only named chains — skip the unnamed LCEL inner nodes (P47)\n        name = kwargs.get(\"name\")\n        if not name or name.startswith(\"RunnableLambda\"):\n            return\n        self._dispatch(\"chain_end\", {\"name\": name, \"run_id\": str(run_id)}, step_index=0)\n\n    async def drain(self, timeout: float = 5.0) -> None:\n        \"\"\"Call before process exit so in-flight dispatches complete.\"\"\"\n        if self._tasks:\n            await asyncio.wait(self._tasks, timeout=timeout)\n```\n\nSee [Async Callback Handler](references\u002Fasync-callback-handler.md) for the full\nhandler — `on_llm_end`, filtering, sync-vs-async decision.\n\n### Step 2 — Pass callbacks via `config` so subgraphs inherit them\n\nP28: `Runnable.with_config(callbacks=[h])` binds at definition and is **not**\ninherited by LangGraph subgraphs. Pass callbacks via `config` at invocation:\n\n```python\n# WRONG — subagent tool calls never fire the handler\nagent_with_handler = agent.with_config({\"callbacks\": [handler]})\nawait agent_with_handler.ainvoke({\"messages\": [...]})\n\n# RIGHT — callbacks in config propagate into subgraphs\nawait agent.ainvoke(\n    {\"messages\": [...]},\n    config={\"callbacks\": [handler], \"configurable\": {\"thread_id\": \"t1\"}},\n)\n```\n\nValidate propagation with a probe that counts events by `kwargs[\"name\"]` and\nasserts the subagent's name appears. See [Subgraph Propagation](references\u002Fsubgraph-propagation.md).\n\n### Step 3 — Pick a dispatch target by delivery semantics\n\nMatch the event to the transport:\n\n| Target | Delivery | Typical latency | Use when | Failure mode |\n|---|---|---|---|---|\n| HTTP webhook | At-least-once (with retry) | 50-500ms | Partner integrations, Zapier\u002FMake, customer-owned endpoints | Endpoint 5xx → retry 1s\u002F5s\u002F30s → DLQ |\n| Kafka (aiokafka) | At-least-once (idempotent producer) | 5-20ms intra-region | High-volume telemetry, analytics fan-in | Broker unavailable → retry + local buffer |\n| Redis Streams (`XADD`) | At-least-once (consumer groups) | 1-5ms | Near-realtime worker queues, progress fan-out | Redis down → retry or spill to disk |\n| SNS | At-most-once (best-effort) | 10-100ms | Fan-out to multiple SQS\u002FLambda subscribers | Best-effort only; accept loss or front with SQS FIFO |\n\nHandler stays provider-agnostic; only the `sink` changes. A minimal HTTP sink:\n\n```python\nimport hashlib, hmac, json, os\nimport httpx\n\nWEBHOOK_URL = os.environ[\"WEBHOOK_URL\"]\nSIGNING_SECRET = os.environ[\"WEBHOOK_SIGNING_SECRET\"].encode()\n\nclass WebhookSink:\n    # 256-bit HMAC — industry-standard signature strength (GitHub, Stripe use same)\n    SIG_ALG = hashlib.sha256\n    # Retry schedule: 1s absorbs transient blips, 5s absorbs brief 503s,\n    # 30s absorbs autoscaler \u002F cold-start incidents. Beyond 30s = stale event.\n    RETRY_DELAYS = (1, 5, 30)\n    REQUEST_TIMEOUT_S = 5.0\n\n    def __init__(self, client: httpx.AsyncClient):\n        self.client = client\n\n    async def send(self, *, idempotency_key: str, event_type: str, payload: dict) -> None:\n        body = json.dumps({\"event\": event_type, \"data\": payload}, sort_keys=True).encode()\n        sig = hmac.new(SIGNING_SECRET, body, self.SIG_ALG).hexdigest()\n        headers = {\n            \"Content-Type\": \"application\u002Fjson\",\n            \"Idempotency-Key\": idempotency_key,\n            \"X-Signature-256\": f\"sha256={sig}\",\n        }\n        for delay in self.RETRY_DELAYS:\n            try:\n                resp = await self.client.post(WEBHOOK_URL, content=body, headers=headers, timeout=self.REQUEST_TIMEOUT_S)\n                if 200 \u003C= resp.status_code \u003C 300:\n                    return\n                if resp.status_code \u003C 500 and resp.status_code != 429:\n                    return  # 4xx (except 429) is not retryable\n            except (httpx.TimeoutException, httpx.TransportError):\n                pass\n            await asyncio.sleep(delay)\n        await self._dead_letter(idempotency_key, event_type, payload)\n```\n\nSee [Dispatch Targets](references\u002Fdispatch-targets.md) for Kafka \u002F Redis Streams\n\u002F SNS sinks and per-target DLQ patterns.\n\n### Step 4 — Filter events so you don't saturate the downstream\n\n`astream_events(version=\"v2\")` emits thousands of events per invocation (P47).\nNever forward raw — dispatch only what the downstream consumes:\n\n| Callback method | Typical decision | Why |\n|---|---|---|\n| `on_llm_start` | Skip | Prompt content often contains PII; low value without masking |\n| `on_llm_new_token` | **Skip for dispatch** (UI only) | 1 event per token; N\u002FA to analytics |\n| `on_llm_end` | Dispatch for named chains only | Token usage, final response — high value, low volume |\n| `on_chain_start` | Skip (P47 noise) | LCEL emits one per inner runnable |\n| `on_chain_end` | Dispatch for named subgraphs only | Stage completion — what analytics cares about |\n| `on_tool_start` | Optional (dispatch for audit log) | Matters for compliance \u002F tool-use audit |\n| `on_tool_end` | **Dispatch always** | The key analytics signal in agent flows |\n| `on_agent_action` | Dispatch | Cleaner signal than `on_tool_start` in agent graphs |\n| `on_agent_finish` | Dispatch | Terminal event for the run |\n\nRule of thumb: dispatch `on_tool_end` + named `on_chain_end` + `on_llm_end`.\nEverything else is noise.\n\n### Step 5 — Build idempotency keys and a retry budget\n\nAt-least-once transports mean duplicates. Build the key deterministically:\n\n```python\n# run_id — unique per chain invocation (propagates into subgraphs)\n# event_type — on_tool_end \u002F on_chain_end \u002F on_llm_end\n# step_index — monotonic per-run counter you maintain in the handler\n\nidempotency_key = f\"{run_id}:{event_type}:{step_index}\"\n```\n\nRetry budget: **1s → 5s → 30s** (~36s total) then DLQ. Retry on 5xx \u002F 429 \u002F\nnetwork only — 4xx (except 429) goes straight to DLQ. DLQ is a Redis Stream\nor S3 prefix keyed by `YYYY\u002FMM\u002FDD\u002Frun_id\u002Fidempotency_key.json`; alarm on depth\ngrowth. See [Idempotency and Retry](references\u002Fidempotency-and-retry.md) for\nHMAC verify, at-least-once vs at-most-once, and 24h de-dup window sizing.\n\n### Step 6 — Never dispatch from `BackgroundTasks` (P60)\n\nFastAPI `BackgroundTasks` run *after* the response closes — exactly wrong for\nper-event dispatch. Events must go out *during* the chain:\n\n```python\n# WRONG — events fire all at once after the stream ends\n@app.post(\"\u002Fchat\")\nasync def chat(req: Request, bg: BackgroundTasks):\n    bg.add_task(agent.ainvoke, {\"messages\": [...]})  # late + no streaming\n    return {\"status\": \"accepted\"}\n\n# RIGHT — handler fires during the chain, each on_tool_end dispatches immediately\n@app.post(\"\u002Fchat\")\nasync def chat(req: ChatReq):\n    handler = EventDispatchHandler(sink=webhook_sink, run_id=req.run_id)\n    try:\n        result = await agent.ainvoke(\n            {\"messages\": req.messages},\n            config={\"callbacks\": [handler], \"configurable\": {\"thread_id\": req.thread_id}},\n        )\n    finally:\n        await handler.drain(timeout=5.0)  # flush in-flight dispatches\n    return {\"result\": result}\n```\n\n`drain()` awaits in-flight `asyncio.create_task()` dispatches up to 5s so\nevents aren't lost when the pod scales down mid-request.\n\n## Output\n\n- Async `BaseCallbackHandler` subclass with `asyncio.create_task()` fire-and-forget\n- Callbacks wired via `config[\"callbacks\"]` at invoke time (subgraph-safe)\n- Per-target sink abstraction: HTTP \u002F Kafka \u002F Redis Streams \u002F SNS\n- HMAC-signed webhook payloads with 1s\u002F5s\u002F30s retry and DLQ fallback\n- Idempotency key = `run_id + event_type + step_index`\n- Event-taxonomy filter: dispatch `on_tool_end` + named `on_chain_end` + `on_llm_end`\n- `drain()` on shutdown to flush in-flight dispatches\n\n## Error Handling\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| Handler fires on outer agent but not subagent | Bound via `with_config` at definition (P28) | Pass via `config[\"callbacks\"]` at `invoke(...)` time |\n| Webhook analytics lags generation duration | `BackgroundTasks` fire post-response (P60) | Dispatch from the callback handler, never from `BackgroundTasks` |\n| Browser \u002F Kafka saturates on long generations | Forwarded `astream_events(v2)` raw (P47) | Filter events server-side; dispatch only `on_tool_end`\u002F`on_chain_end`\u002F`on_llm_end` |\n| SSE stream hangs, no end event | Proxy buffering (P46) | Set `X-Accel-Buffering: no` — see `langchain-langgraph-streaming` |\n| Event loop freezes on slow webhook | Sync POST in callback (P48) | Subclass `AsyncCallbackHandler`; use `asyncio.create_task()` |\n| Duplicate events downstream | At-least-once dispatch + retry | Receiver dedupes on `Idempotency-Key` header with 24h cache |\n| Orphan `asyncio.create_task` never runs | GC collected the task | Hold a strong reference in `self._tasks` and discard on completion |\n| Events lost on pod shutdown | In-flight tasks cancelled | Call `await handler.drain(timeout=5.0)` in endpoint `finally` block |\n| 4xx webhook errors retrying 3x | Retry logic retrying everything | Retry only on 5xx \u002F 429 \u002F network; 4xx goes straight to DLQ |\n| Signature verification fails on receiver | Body re-serialized with different key order | Sign the exact bytes you send; use `sort_keys=True` in `json.dumps` |\n\n## Examples\n\n### Named subgraph dispatch with a LangGraph agent\n\nPlanner subagent runs `search_docs` → `summarize`; outer agent needs a webhook\non `summarize` completion. Full wiring in [Subgraph Propagation](references\u002Fsubgraph-propagation.md).\n\n### Fan-out: webhook + Kafka + Redis Streams in one invocation\n\n`CompositeSink` dispatches to multiple child sinks via\n`asyncio.gather(..., return_exceptions=True)` — one sink's failure doesn't block\nothers. See [Dispatch Targets](references\u002Fdispatch-targets.md).\n\n### HMAC-signed webhook receiver with de-dup\n\nVerify `X-Signature-256`, SETNX `Idempotency-Key` against Redis with 24h TTL,\n200 on both replay and first-seen. See [Idempotency and Retry](references\u002Fidempotency-and-retry.md).\n\n## Resources\n\n- [LangChain callbacks concepts](https:\u002F\u002Fpython.langchain.com\u002Fdocs\u002Fconcepts\u002Fcallbacks\u002F)\n- [`BaseCallbackHandler` \u002F `AsyncCallbackHandler` API](https:\u002F\u002Fpython.langchain.com\u002Fapi_reference\u002Fcore\u002Fcallbacks\u002Flangchain_core.callbacks.base.BaseCallbackHandler.html)\n- [`astream_events` v2 events reference](https:\u002F\u002Fpython.langchain.com\u002Fdocs\u002Fhow_to\u002Fstreaming\u002F#using-stream-events)\n- [LangGraph streaming concepts](https:\u002F\u002Flangchain-ai.github.io\u002Flanggraph\u002Fconcepts\u002Fstreaming\u002F)\n- [FastAPI BackgroundTasks — note the \"after response\" semantics](https:\u002F\u002Ffastapi.tiangolo.com\u002Ftutorial\u002Fbackground-tasks\u002F)\n- [aiokafka producer idempotence](https:\u002F\u002Faiokafka.readthedocs.io\u002Fen\u002Fstable\u002Fproducer.html)\n- [Redis Streams `XADD` \u002F consumer groups](https:\u002F\u002Fredis.io\u002Fdocs\u002Flatest\u002Fcommands\u002Fxadd\u002F)\n- Cross-reference in this pack: `langchain-langgraph-streaming` (UI streaming), `langchain-debug-bundle` (callback-propagation debugging)\n- Pack pain catalog: `docs\u002Fpain-catalog.md` (entries P28, P46, P47, P48, P60)\n","# LangChain Webhooks and Event Dispatch (Python)\n\n## Overview\n\nA team wires per-tool webhook dispatch from their LangChain agent via FastAPI\n`BackgroundTasks` — analytics is always N seconds late because `BackgroundTasks`\nfire **after** the HTTP response closes, not during the stream (P60). Worse:\nthe `BaseCallbackHandler` they attached via `.with_config(callbacks=[h])`\nfires on the outer agent but is dark on the subagent's tool calls — custom\ncallbacks are **not** inherited by LangGraph subgraphs (P28), they must be\npassed via `config[\"callbacks\"]` at invoke time.\n\nPain-catalog anchors handled here:\n\n- P28 — Callbacks via `with_config` don't propagate to subgraphs\n- P46 — SSE streams dropped by buffering proxies (see `langchain-langgraph-streaming`)\n- P47 — `astream_events(v2)` emits thousands of events; never forward raw\n- P48 — Sync `invoke()` inside async endpoint blocks the event loop\n- P60 — `BackgroundTasks` fire post-response; wrong for per-event dispatch\n\nThis skill walks through an async `AsyncCallbackHandler` with fire-and-forget\ndispatch, per-target sinks for HTTP \u002F Kafka \u002F Redis Streams \u002F SNS, HMAC-signed\ndelivery with 1s\u002F5s\u002F30s retry and DLQ, idempotency keys = `run_id + event_type\n+ step_index`, and `config[\"callbacks\"]` wiring that makes subagent calls visible.\nTypical webhook latency budget: \u003C500ms per event. Pin: `langchain-core 1.0.x`,\n`langgraph 1.0.x`. Scope: server-to-server dispatch only — UI streaming is in\n`langchain-langgraph-streaming`.\n\n## Prerequisites\n\n- Python 3.10+\n- `langchain-core >= 1.0, \u003C 2.0`, `langgraph >= 1.0, \u003C 2.0`\n- `httpx >= 0.27` for async HTTP (or `aiohttp`)\n- One of: `aiokafka`, `redis[hiredis] >= 5`, `aioboto3` (per target)\n- An event sink — a webhook endpoint, Kafka topic, Redis Stream, or SNS topic\n- A shared secret (for HMAC) stored in your secret manager, not env\n\n## Instructions\n\n### Step 1 — Write an async handler that fire-and-forget dispatches\n\nSync dispatch from a callback blocks the chain — a slow HTTP POST during\n`on_tool_end` serializes all downstream tokens behind it (P48). Use\n`asyncio.create_task(...)` so the dispatch runs alongside the chain:\n\n```python\nimport asyncio\nimport uuid\nfrom typing import Any\nfrom langchain_core.callbacks import AsyncCallbackHandler\n\nclass EventDispatchHandler(AsyncCallbackHandler):\n    \"\"\"Fire-and-forget dispatch to external sinks.\n\n    IMPORTANT: subclass AsyncCallbackHandler (not BaseCallbackHandler) so\n    on_* methods are awaited. Mixing sync and async handlers is a silent\n    footgun — sync on_* blocks the event loop (P48).\n    \"\"\"\n\n    def __init__(self, sink, *, run_id: str | None = None):\n        self.sink = sink                      # dispatch target — Step 3\n        self.run_id = run_id or str(uuid.uuid4())\n        self._tasks: set[asyncio.Task] = set()\n\n    def _dispatch(self, event_type: str, payload: dict, step_index: int) -> None:\n        # Fire-and-forget. Keep a strong reference so the task isn't GC'd\n        # mid-flight (asyncio quirk — orphan tasks get garbage-collected).\n        task = asyncio.create_task(\n            self.sink.send(\n                idempotency_key=f\"{self.run_id}:{event_type}:{step_index}\",\n                event_type=event_type,\n                payload=payload,\n            )\n        )\n        self._tasks.add(task)\n        task.add_done_callback(self._tasks.discard)\n\n    async def on_tool_end(self, output: Any, *, run_id, parent_run_id=None, **kwargs):\n        # 4000 char cap — keep payload under typical webhook body limits\n        # while preserving enough context for downstream analytics.\n        MAX_OUTPUT_CHARS = 4000\n        self._dispatch(\n            \"tool_end\",\n            {\"output\": str(output)[:MAX_OUTPUT_CHARS], \"run_id\": str(run_id)},\n            step_index=kwargs.get(\"tags\", []).__len__() or 0,\n        )\n\n    async def on_chain_end(self, outputs: dict, *, run_id, **kwargs):\n        # Only named chains — skip the unnamed LCEL inner nodes (P47)\n        name = kwargs.get(\"name\")\n        if not name or name.startswith(\"RunnableLambda\"):\n            return\n        self._dispatch(\"chain_end\", {\"name\": name, \"run_id\": str(run_id)}, step_index=0)\n\n    async def drain(self, timeout: float = 5.0) -> None:\n        \"\"\"Call before process exit so in-flight dispatches complete.\"\"\"\n        if self._tasks:\n            await asyncio.wait(self._tasks, timeout=timeout)\n```\n\nSee [Async Callback Handler](references\u002Fasync-callback-handler.md) for the full\nhandler — `on_llm_end`, filtering, sync-vs-async decision.\n\n### Step 2 — Pass callbacks via `config` so subgraphs inherit them\n\nP28: `Runnable.with_config(callbacks=[h])` binds at definition and is **not**\ninherited by LangGraph subgraphs. Pass callbacks via `config` at invocation:\n\n```python\n# WRONG — subagent tool calls never fire the handler\nagent_with_handler = agent.with_config({\"callbacks\": [handler]})\nawait agent_with_handler.ainvoke({\"messages\": [...]})\n\n# RIGHT — callbacks in config propagate into subgraphs\nawait agent.ainvoke(\n    {\"messages\": [...]},\n    config={\"callbacks\": [handler], \"configurable\": {\"thread_id\": \"t1\"}},\n)\n```\n\nValidate propagation with a probe that counts events by `kwargs[\"name\"]` and\nasserts the subagent's name appears. See [Subgraph Propagation](references\u002Fsubgraph-propagation.md).\n\n### Step 3 — Pick a dispatch target by delivery semantics\n\nMatch the event to the transport:\n\n| Target | Delivery | Typical latency | Use when | Failure mode |\n|---|---|---|---|---|\n| HTTP webhook | At-least-once (with retry) | 50-500ms | Partner integrations, Zapier\u002FMake, customer-owned endpoints | Endpoint 5xx → retry 1s\u002F5s\u002F30s → DLQ |\n| Kafka (aiokafka) | At-least-once (idempotent producer) | 5-20ms intra-region | High-volume telemetry, analytics fan-in | Broker unavailable → retry + local buffer |\n| Redis Streams (`XADD`) | At-least-once (consumer groups) | 1-5ms | Near-realtime worker queues, progress fan-out | Redis down → retry or spill to disk |\n| SNS | At-most-once (best-effort) | 10-100ms | Fan-out to multiple SQS\u002FLambda subscribers | Best-effort only; accept loss or front with SQS FIFO |\n\nHandler stays provider-agnostic; only the `sink` changes. A minimal HTTP sink:\n\n```python\nimport hashlib, hmac, json, os\nimport httpx\n\nWEBHOOK_URL = os.environ[\"WEBHOOK_URL\"]\nSIGNING_SECRET = os.environ[\"WEBHOOK_SIGNING_SECRET\"].encode()\n\nclass WebhookSink:\n    # 256-bit HMAC — industry-standard signature strength (GitHub, Stripe use same)\n    SIG_ALG = hashlib.sha256\n    # Retry schedule: 1s absorbs transient blips, 5s absorbs brief 503s,\n    # 30s absorbs autoscaler \u002F cold-start incidents. Beyond 30s = stale event.\n    RETRY_DELAYS = (1, 5, 30)\n    REQUEST_TIMEOUT_S = 5.0\n\n    def __init__(self, client: httpx.AsyncClient):\n        self.client = client\n\n    async def send(self, *, idempotency_key: str, event_type: str, payload: dict) -> None:\n        body = json.dumps({\"event\": event_type, \"data\": payload}, sort_keys=True).encode()\n        sig = hmac.new(SIGNING_SECRET, body, self.SIG_ALG).hexdigest()\n        headers = {\n            \"Content-Type\": \"application\u002Fjson\",\n            \"Idempotency-Key\": idempotency_key,\n            \"X-Signature-256\": f\"sha256={sig}\",\n        }\n        for delay in self.RETRY_DELAYS:\n            try:\n                resp = await self.client.post(WEBHOOK_URL, content=body, headers=headers, timeout=self.REQUEST_TIMEOUT_S)\n                if 200 \u003C= resp.status_code \u003C 300:\n                    return\n                if resp.status_code \u003C 500 and resp.status_code != 429:\n                    return  # 4xx (except 429) is not retryable\n            except (httpx.TimeoutException, httpx.TransportError):\n                pass\n            await asyncio.sleep(delay)\n        await self._dead_letter(idempotency_key, event_type, payload)\n```\n\nSee [Dispatch Targets](references\u002Fdispatch-targets.md) for Kafka \u002F Redis Streams\n\u002F SNS sinks and per-target DLQ patterns.\n\n### Step 4 — Filter events so you don't saturate the downstream\n\n`astream_events(version=\"v2\")` emits thousands of events per invocation (P47).\nNever forward raw — dispatch only what the downstream consumes:\n\n| Callback method | Typical decision | Why |\n|---|---|---|\n| `on_llm_start` | Skip | Prompt content often contains PII; low value without masking |\n| `on_llm_new_token` | **Skip for dispatch** (UI only) | 1 event per token; N\u002FA to analytics |\n| `on_llm_end` | Dispatch for named chains only | Token usage, final response — high value, low volume |\n| `on_chain_start` | Skip (P47 noise) | LCEL emits one per inner runnable |\n| `on_chain_end` | Dispatch for named subgraphs only | Stage completion — what analytics cares about |\n| `on_tool_start` | Optional (dispatch for audit log) | Matters for compliance \u002F tool-use audit |\n| `on_tool_end` | **Dispatch always** | The key analytics signal in agent flows |\n| `on_agent_action` | Dispatch | Cleaner signal than `on_tool_start` in agent graphs |\n| `on_agent_finish` | Dispatch | Terminal event for the run |\n\nRule of thumb: dispatch `on_tool_end` + named `on_chain_end` + `on_llm_end`.\nEverything else is noise.\n\n### Step 5 — Build idempotency keys and a retry budget\n\nAt-least-once transports mean duplicates. Build the key deterministically:\n\n```python\n# run_id — unique per chain invocation (propagates into subgraphs)\n# event_type — on_tool_end \u002F on_chain_end \u002F on_llm_end\n# step_index — monotonic per-run counter you maintain in the handler\n\nidempotency_key = f\"{run_id}:{event_type}:{step_index}\"\n```\n\nRetry budget: **1s → 5s → 30s** (~36s total) then DLQ. Retry on 5xx \u002F 429 \u002F\nnetwork only — 4xx (except 429) goes straight to DLQ. DLQ is a Redis Stream\nor S3 prefix keyed by `YYYY\u002FMM\u002FDD\u002Frun_id\u002Fidempotency_key.json`; alarm on depth\ngrowth. See [Idempotency and Retry](references\u002Fidempotency-and-retry.md) for\nHMAC verify, at-least-once vs at-most-once, and 24h de-dup window sizing.\n\n### Step 6 — Never dispatch from `BackgroundTasks` (P60)\n\nFastAPI `BackgroundTasks` run *after* the response closes — exactly wrong for\nper-event dispatch. Events must go out *during* the chain:\n\n```python\n# WRONG — events fire all at once after the stream ends\n@app.post(\"\u002Fchat\")\nasync def chat(req: Request, bg: BackgroundTasks):\n    bg.add_task(agent.ainvoke, {\"messages\": [...]})  # late + no streaming\n    return {\"status\": \"accepted\"}\n\n# RIGHT — handler fires during the chain, each on_tool_end dispatches immediately\n@app.post(\"\u002Fchat\")\nasync def chat(req: ChatReq):\n    handler = EventDispatchHandler(sink=webhook_sink, run_id=req.run_id)\n    try:\n        result = await agent.ainvoke(\n            {\"messages\": req.messages},\n            config={\"callbacks\": [handler], \"configurable\": {\"thread_id\": req.thread_id}},\n        )\n    finally:\n        await handler.drain(timeout=5.0)  # flush in-flight dispatches\n    return {\"result\": result}\n```\n\n`drain()` awaits in-flight `asyncio.create_task()` dispatches up to 5s so\nevents aren't lost when the pod scales down mid-request.\n\n## Output\n\n- Async `BaseCallbackHandler` subclass with `asyncio.create_task()` fire-and-forget\n- Callbacks wired via `config[\"callbacks\"]` at invoke time (subgraph-safe)\n- Per-target sink abstraction: HTTP \u002F Kafka \u002F Redis Streams \u002F SNS\n- HMAC-signed webhook payloads with 1s\u002F5s\u002F30s retry and DLQ fallback\n- Idempotency key = `run_id + event_type + step_index`\n- Event-taxonomy filter: dispatch `on_tool_end` + named `on_chain_end` + `on_llm_end`\n- `drain()` on shutdown to flush in-flight dispatches\n\n## Error Handling\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| Handler fires on outer agent but not subagent | Bound via `with_config` at definition (P28) | Pass via `config[\"callbacks\"]` at `invoke(...)` time |\n| Webhook analytics lags generation duration | `BackgroundTasks` fire post-response (P60) | Dispatch from the callback handler, never from `BackgroundTasks` |\n| Browser \u002F Kafka saturates on long generations | Forwarded `astream_events(v2)` raw (P47) | Filter events server-side; dispatch only `on_tool_end`\u002F`on_chain_end`\u002F`on_llm_end` |\n| SSE stream hangs, no end event | Proxy buffering (P46) | Set `X-Accel-Buffering: no` — see `langchain-langgraph-streaming` |\n| Event loop freezes on slow webhook | Sync POST in callback (P48) | Subclass `AsyncCallbackHandler`; use `asyncio.create_task()` |\n| Duplicate events downstream | At-least-once dispatch + retry | Receiver dedupes on `Idempotency-Key` header with 24h cache |\n| Orphan `asyncio.create_task` never runs | GC collected the task | Hold a strong reference in `self._tasks` and discard on completion |\n| Events lost on pod shutdown | In-flight tasks cancelled | Call `await handler.drain(timeout=5.0)` in endpoint `finally` block |\n| 4xx webhook errors retrying 3x | Retry logic retrying everything | Retry only on 5xx \u002F 429 \u002F network; 4xx goes straight to DLQ |\n| Signature verification fails on receiver | Body re-serialized with different key order | Sign the exact bytes you send; use `sort_keys=True` in `json.dumps` |\n\n## Examples\n\n### Named subgraph dispatch with a LangGraph agent\n\nPlanner subagent runs `search_docs` → `summarize`; outer agent needs a webhook\non `summarize` completion. Full wiring in [Subgraph Propagation](references\u002Fsubgraph-propagation.md).\n\n### Fan-out: webhook + Kafka + Redis Streams in one invocation\n\n`CompositeSink` dispatches to multiple child sinks via\n`asyncio.gather(..., return_exceptions=True)` — one sink's failure doesn't block\nothers. See [Dispatch Targets](references\u002Fdispatch-targets.md).\n\n### HMAC-signed webhook receiver with de-dup\n\nVerify `X-Signature-256`, SETNX `Idempotency-Key` against Redis with 24h TTL,\n200 on both replay and first-seen. See [Idempotency and Retry](references\u002Fidempotency-and-retry.md).\n\n## Resources\n\n- [LangChain callbacks concepts](https:\u002F\u002Fpython.langchain.com\u002Fdocs\u002Fconcepts\u002Fcallbacks\u002F)\n- [`BaseCallbackHandler` \u002F `AsyncCallbackHandler` API](https:\u002F\u002Fpython.langchain.com\u002Fapi_reference\u002Fcore\u002Fcallbacks\u002Flangchain_core.callbacks.base.BaseCallbackHandler.html)\n- [`astream_events` v2 events reference](https:\u002F\u002Fpython.langchain.com\u002Fdocs\u002Fhow_to\u002Fstreaming\u002F#using-stream-events)\n- [LangGraph streaming concepts](https:\u002F\u002Flangchain-ai.github.io\u002Flanggraph\u002Fconcepts\u002Fstreaming\u002F)\n- [FastAPI BackgroundTasks — note the \"after response\" semantics](https:\u002F\u002Ffastapi.tiangolo.com\u002Ftutorial\u002Fbackground-tasks\u002F)\n- [aiokafka producer idempotence](https:\u002F\u002Faiokafka.readthedocs.io\u002Fen\u002Fstable\u002Fproducer.html)\n- [Redis Streams `XADD` \u002F consumer groups](https:\u002F\u002Fredis.io\u002Fdocs\u002Flatest\u002Fcommands\u002Fxadd\u002F)\n- Cross-reference in this pack: `langchain-langgraph-streaming` (UI streaming), `langchain-debug-bundle` (callback-propagation debugging)\n- Pack pain catalog: `docs\u002Fpain-catalog.md` (entries P28, P46, P47, P48, P60)\n",{"name":5,"tags":24,"author":34,"license":15,"version":35,"description":36,"allowed-tools":37,"compatible-with":38},[25,26,27,28,29,30,31,32,33],"saas","langchain","langgraph","python","langchain-1.0","webhooks","async","events","callbacks","Jeremy Longshore \u003Cjeremy@intentsolutions.io>","2.0.0","Dispatch LangChain 1.0 chain\u002Fagent events to external systems — webhooks, Kafka,\nRedis Streams, SNS — via async fire-and-forget callbacks, subgraph-aware wiring,\nand HMAC-signed delivery with idempotency keys. Use when firing webhooks on tool\ncalls, pushing telemetry to Kafka \u002F Redis Streams, or fanning progress to multiple\nsubscribers without blocking the chain.\nTrigger with \"langchain webhook\", \"langchain event dispatch\", \"langchain callback kafka\",\n\"langchain pubsub\", \"langchain per-tool webhook\", \"BaseCallbackHandler webhook\",\n\"on_tool_end webhook\", \"langchain analytics event\".\n","Read, Write, Edit, Bash(python:*)","claude-code, codex","main","99825ad3f3bcc6597ddcc7294a14e6e922f2b67b","skills\u002Fsaas-packs--langchain-py-pack--langchain-webhooks-events",0,"https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills","https:\u002F\u002Fgithub.com\u002Fjukeyman","https:\u002F\u002FRJBUSINESSSOLUTIONS.ORG","Credit and Finance Expert | Developer\r\n\r\nI'm Rick Jefferson, a seasoned credit and finance expert with over a decade of experience in financial literacy,","2026-07-13 07:03:29",{"source":8,"skillName":5,"commands":49,"prompt":59,"zipAvailable":60},[50,53,56],{"tool":51,"command":52},"npx","npx skills add jukeyman\u002Fjukeyman-skills --skill langchain-webhooks-events",{"tool":54,"command":55},"bunx","bunx skills add jukeyman\u002Fjukeyman-skills --skill langchain-webhooks-events",{"tool":57,"command":58},"pnpm","pnpm dlx skills add jukeyman\u002Fjukeyman-skills --skill langchain-webhooks-events","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsaas-packs--langchain-py-pack--langchain-webhooks-events\u002FSKILL.md",true,[],[63,70,77,84,91,99],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M79ANS2SM329NEP5ZCX106RR","zustand-store-creator","Create zustand store creator operations. Auto-activating skill for Frontend Development.\nTriggers on: zustand store creator, zustand store creator\nPart of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like \"zustand store creator\", \"zustand creator\", \"zustand\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzustand-store-creator\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M79AMZKP4YDEZ7EHG1Y7PP74","zero-trust-config-helper","Configure with zero trust config helper operations. Auto-activating skill for Security Advanced.\nTriggers on: zero trust config helper, zero trust config helper\nPart of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like \"zero trust config helper\", \"zero helper\", \"zero\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzero-trust-config-helper\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M79AMJSBCEJQNBTYNAHYN5HM","zapier-integration-helper","Assist with zapier integration helper operations. Auto-activating skill for Business Automation.\nTriggers on: zapier integration helper, zapier integration helper\nPart of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like \"zapier integration helper\", \"zapier helper\", \"zapier\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzapier-integration-helper\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M79AHJZGVMARS13VFQYRR1MP","yaml-config-validator","Validate yaml config validator operations. Auto-activating skill for DevOps Basics.\nTriggers on: yaml config validator, yaml config validator\nPart of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like \"yaml config validator\", \"yaml validator\", \"yaml\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fyaml-config-validator\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":95,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M79AHGDZRN0020RDQSQDPAM8","xvary-stock-research","Thesis-driven equity analysis from public SEC EDGAR and market data; \u002Fanalyze, \u002Fscore, \u002Fcompare workflows with bundled Python tools (Claude Code, Cursor, Codex).","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxvary-stock-research\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxvary-stock-research\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M79AHCYJ9FV9RMHQ24HDRN33","xss-vulnerability-scanner","Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals.\nTriggers on: xss vulnerability scanner, xss vulnerability scanner\nPart of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like \"xss vulnerability scanner\", \"xss scanner\", \"xss\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxss-vulnerability-scanner\u002FSKILL.md",[],[]]