Webhook API
一个 webhook 属于一个表单。另一个系统带着 bearer 密钥向它发送一个 JSON 请求体;Pyn 接受负载,然后另行把它变成表单上一次以它指定的员工为名的提交,并把结果记录在 webhook 的日志中。创建 webhook介绍应用中的设置过程。
POST https://<your Pyn host>/api/webhook/<webhookId>Authorization: Bearer <secret>Content-Type: application/jsonIdempotency-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 |
已丢弃 | 某个键不对应表单上的任何字段,或某个值的类型与字段不符。 |
每个被丢弃的负载还会在通知中生成一条通知;反复犯同一个错误的调用方只会更新同一条通知。
| 操作 | 效果 |
|---|---|
| Create Secret | 为还没有密钥的 webhook 生成密钥。没有密钥的 webhook 不接受任何内容。 |
| Replace Secret | 生成一个新密钥;旧密钥立即失效。 |
密钥只显示一次,无法再次读取。两个操作都需要 Admin。
- 创建 webhook,了解应用中的步骤。
- 表单字段类型,了解每个字段接受的值。
- 通知,了解被丢弃的负载显示在哪里。