---
title: "Webhook API"
description: "表单上的入站 webhook：端点、bearer 密钥、带 subject_id 和 fields 的 JSON 请求体、幂等键、两种响应、每位员工只提交一次的规则，以及日志可能记录的每一个代码。"
sidebar:
  order: 3
area: flows
feature: forms
appPath: /flows/home
lastVerified: 2026-11-15
version: "2026-10-23"
audience: admin
related:
  - flows/forms/create-a-webhook
  - flows/forms/reference-form-field-types
  - notices
intercom:
  - id: "16858360"
    title: Create a Webhook (Pyn 2)
    url: https://intercom.help/pyn/en/articles/16858360-create-a-webhook-pyn-2
    note: draws on
translation:
  source: flows/forms/reference-webhook-api.mdx
  sourceSha: 2c607d39875f121d7d36587eff499f6edebd6ed7
---

一个 webhook 属于一个表单。另一个系统带着 bearer 密钥向它发送一个 JSON 请求体；Pyn 接受负载，然后另行把它变成表单上一次以它指定的员工为名的提交，并把结果记录在 webhook 的日志中。[创建 webhook](https://support.pyn.ai/zh-cn/flows/forms/create-a-webhook/)介绍应用中的设置过程。

## 请求

```
POST https://<your Pyn host>/api/webhook/<webhookId>
Authorization: Bearer <secret>
Content-Type: application/json
Idempotency-Key: <any string>      (optional)

{
  "subject_id": "E1234",
  "fields": {
    "jobTitle": "Account Executive",
    "startedOnboarding": true,
    "firstWeekRating": 4
  }
}
```

- `webhookId` 和密钥来自表单的 **Settings** 侧面板。密钥只在生成时显示一次。
- `subject_id` 是员工在表单 **Subject** 下所选来源系统中的 id（例如 BambooHR Employee ID）。Pyn 查找持有该系统中这个 id 的员工；来自另一个系统的同一个 id 不会匹配。
- `fields` 为每个表单字段放一个条目，以字段的别名（驼峰形式的标签）或键命名。每个键都必须对应表单上的一个字段，每个值都必须是该字段能够保存的：**Text** 是不超过 2,048 个字符的字符串，**Checkbox** 是 `true` 或 `false`，**Likert Scale** 是 1 到 5 的整数，**Buddy** 和 **Mentor** 是 Pyn 的员工 id（36 个字符，不是 HRIS id）。**Content** 字段不接受值。
- 请求体必须是一个 JSON 对象。把值嵌套在 `fields` 下，可以避免字段名与 `subject_id` 冲突。

## 响应

| 状态 | 含义 |
| --- | --- |
| `202` | 已接受。负载已被接收并将被处理；这不代表提交成功。请阅读日志。 |
| `404` | 已拒绝：id 格式错误或未知、webhook 已归档，或 bearer 密钥不匹配。这些情况不作区分，所以端点无法被探测。 |

到达端点但请求体不是 JSON 的请求，或在 Pyn 一侧出现故障期间的请求，会得到常规的 `4xx` 或 `5xx`；`5xx` 可以重试。

## 幂等性

发送一个 `Idempotency-Key` 请求头，之后向同一个 webhook 重复发送同一个键，会得到 `202` 的确认，但不再被处理。把同一个键发给另一个 webhook 算作另一次投递。没有这个请求头，每一次发送都会被处理。日志中的 `eventId` 是追踪一次投递的依据。

## 处理规则

- 一个 webhook 为每位员工最多提交一次。某个主体的提交完成后，同一个 `subject_id` 之后的负载会以 `already-submitted` 丢弃。需要同一个人反复回答的表单，不能用 webhook 为他们提交。
- 负载要么整体接受，要么整体拒绝：缺少必填字段或某个值类型错误，会丢弃整个负载，而不是记录一次部分提交。
- 没有设置 **Subject** 的表单不接受任何内容（`no-subject`）。
- 被接受的提交与其他提交表现一致：它出现在表单的 **Activity** 侧面板和导出中，把 Buddy 或 Mentor 值写到员工记录上，并启动该表单上任何带 **Form Submission** 触发器的自动化流程。

## 日志代码

每个负载都会在 webhook 的日志中留下一条记录（在表单的 **Settings** 侧面板中，并可把整个日志导出为 CSV）。

| 代码 | 结果 | 含义 |
| --- | --- | --- |
| `submitted` | 已处理 | 为该标识符记录了一次提交。 |
| `no-subject` | 已丢弃 | 表单没有配置 webhook 主体。 |
| `invalid-payload` | 已丢弃 | 请求体无法解析为 `{ subject_id, fields }`；消息中指出字段和原因。 |
| `unknown-subject` | 已丢弃 | 在所选来源系统中没有员工持有该标识符。 |
| `already-submitted` | 已丢弃 | 这个 webhook 已经为该标识符提交过。 |
| `ambiguous-fields` | 已丢弃 | 一个名称匹配了多个字段，或一个字段被命名了两次（同时用键和别名）。 |
| `missing-fields` | 已丢弃 | 未提供某个必填字段。 |
| `invalid-fields` | 已丢弃 | 某个键不对应表单上的任何字段，或某个值的类型与字段不符。 |

每个被丢弃的负载还会在[通知](https://support.pyn.ai/zh-cn/notices/)中生成一条通知；反复犯同一个错误的调用方只会更新同一条通知。

## 密钥

| 操作 | 效果 |
| --- | --- |
| **Create Secret** | 为还没有密钥的 webhook 生成密钥。没有密钥的 webhook 不接受任何内容。 |
| **Replace Secret** | 生成一个新密钥；旧密钥立即失效。 |

密钥只显示一次，无法再次读取。两个操作都需要 Admin。

## 相关

- [创建 webhook](https://support.pyn.ai/zh-cn/flows/forms/create-a-webhook/)，了解应用中的步骤。
- [表单字段类型](https://support.pyn.ai/zh-cn/flows/forms/reference-form-field-types/)，了解每个字段接受的值。
- [通知](https://support.pyn.ai/zh-cn/notices/)，了解被丢弃的负载显示在哪里。
