outpost

Hookdeck Outpost

出站事件投递：将平台事件发布到租户的目标位置（webhook、队列、云总线——请参阅支持的目标位置）。在 GitHub 上开源；可在 Hookdeck Cloud 上托管，也可自托管。

**唯一事实来源：**概念、API、快速入门和 UI 指南请参阅 Hookdeck Outpost 文档。此技能会链接到该文档，并在 references/ 下补充 Agent 工作流说明。

API 基础 URL 和凭据

托管版 Outpost API 的地址为 https://api.outpost.hookdeck.com/2025-07-01，而不是 api.hookdeck.com。使用属于 Outpost 项目的 Hookdeck 项目 API 密钥进行身份验证（Hookdeck Dashboard → 你的 Outpost 项目 → Settings → Secrets），并将其作为 bearer token 发送。请将密钥保留在服务端。

export OUTPOST_API_BASE_URL="https://api.outpost.hookdeck.com/2025-07-01"
export OUTPOST_API_KEY="..."   # key from an Outpost project

# Upsert a tenant: 201 if Outpost created it, 200 if it already existed
curl --request PUT "$OUTPOST_API_BASE_URL/tenants/customer_acme_001" \
  --header "Authorization: Bearer $OUTPOST_API_KEY"

Hookdeck 提供组织 API 密钥和项目 API 密钥。对于 Outpost 服务端任务，请使用项目 API 密钥——关键在于它所属的项目。

非 Outpost 项目的密钥可通过 api.hookdeck.com 完成身份验证，也能与 Hookdeck CLI 配合使用，因此看起来是正确的，但在大多数 Outpost 路由上会返回 404 Not Found。应将此 404 理解为此密钥属于错误的项目，而不是“此账户尚未开通 Outpost”，并向用户索取 Outpost 项目的密钥。不要改用 api.hookdeck.com 来实现任务——那属于Event Gateway，是另一款产品。

面向 Agent 的文档索引

• llms.txt： https://hookdeck.com/docs/outpost/llms.txt — 文档页面的纯文本索引，页面以 .md URL 形式列出；需要查看完整目录或多个页面时，获取一次即可。
• 概念： 租户、目标位置、主题、发布
• API 参考： REST / OpenAPI；自托管规范文件：https://github.com/hookdeck/outpost/blob/main/docs/apis/openapi.yaml
• SDK： 概览 — 使用 TypeScript、Python 或 Go 时，请遵循对应语言的快速入门，以使用正确的签名。
• 构建自己的 UI： 指南 — 屏幕流程、BFF 模式、实施检查清单。
• 目标位置 / 主题： 目标位置类型 · 主题和订阅

快速入门（优先选择最精简的路径）

在打开此仓库中的全栈示例之前，请先使用官方托管版 Outpost 演练：

curl（仅限 HTTP）	Hookdeck Outpost curl 快速入门
TypeScript	TypeScript 快速入门
Python	Python 快速入门
Go	Go 快速入门

精简链接列表：references/outpost-quickstarts.md。

测试 webhook 目标 URL（README 和文档）

当你需要用于 webhook 目标位置的临时 HTTPS URL（快速入门、curl 示例、“验证投递”）时：

• 优先使用 Hookdeck Console — 创建一个 Source，复制其 URL（例如 https://hkdk.events/…），然后在同一处检查或重放投递。这是面向 Agent 和用户的 Hookdeck 原生默认选项。

面向 Agent 的快速路径

1. 从 references/outpost-scope.md 开始，选择 Quick path、New minimal app 或 Existing app。
2. 如果范围不明确，默认选择最小的快速入门式产物。
3. 仅获取所需语言的快速入门指南（curl、TypeScript、Python、Go）。
4. 完成前，使用 references/outpost-verify.md。
5. 只有在任务明确需要 BFF/UI 集成模式时，才打开全栈示例。

范围与验证（Agent 工作流）

仪表板式指南（不含 {{PLACEHOLDERS}}——这些内容仅供仪表板使用）：

• references/outpost-scope.md — 三路径阶梯、默认选择最小方案、语言与架构、主题协调，以及带有 Building your own UI 锚点链接的 SDK 与 OpenAPI / BFF 指引。
• references/outpost-verify.md — 精简的“停止前”检查清单。

BFF / 线路 JSON： Authentication · 线路 JSON、SDK 响应与你的 UI

支持的目标类型

可用： Webhooks（HTTP）、Hookdeck Event Gateway、AWS SQS、AWS Kinesis、AWS S3、Azure Service Bus、GCP Pub/Sub、RabbitMQ（AMQP）、Kafka

计划中： AWS EventBridge

部署与 API 指引

• 托管： Hookdeck Outpost 文档 和各语言的快速入门指南。
• 可自托管的快速入门指南： Docker、Kubernetes、Railway、配置。
• API 参考： Outpost REST / OpenAPI。
• 基础 URL 和身份验证： https://api.outpost.hookdeck.com/2025-07-01，配合 Outpost 项目的项目 API 密钥使用——参见 API 基础 URL 和凭据。

全栈参考示例（高级）

仅在任务需要真实的 BFF + 仪表板模式时使用——不要用于“最小示例”（请先使用 Quickstarts 和 llms.txt）。

集成映射（打开目录树前阅读）：

• Next.js：references/nextjs-saas-integration-map.md
• FastAPI：references/fastapi-saas-integration-map.md

将示例视为参考，而非可直接复制的脚手架。 优先使用用户的代码库，并通过映射了解 Outpost 特有的行为（仅限服务端使用的 Outpost 项目 API 密钥、租户映射、BFF 路由、领域 publish）。

示例	技术栈	位置
SaaS（Next.js）	App Router + @hookdeck/outpost-sdk + 仪表板 UI	examples/nextjs-saas/ — README
SaaS（FastAPI + React）	FastAPI BFF（httpx → Outpost）+ 模板 UI	examples/fastapi-saas/ — README

依赖项和版本固定信息位于示例清单文件（package.json、pyproject.toml）中。

如何使用示例： 先阅读集成映射和 README 概览；仅在其他文件与用户任务相关时才打开。

测试： 在 nextjs-saas 中运行 npm test（Vitest）；在 fastapi-saas/backend 中通过 ./scripts/test-examples.sh outpost 运行 pytest test_outpost_wire.py。Next.js 示例使用 npm。

未来技能

随着文档日趋完善，可能会添加特定目标的技能（outpost-webhooks、outpost-sqs，等等）。

相关技能

• hookdeck — Hookdeck 产品的技能路由器
• event-gateway — Hookdeck Event Gateway（入站 Webhook）