跳转到内容
PynPyn

Webhook API

一个 webhook 属于一个表单。另一个系统带着 bearer 密钥向它发送一个 JSON 请求体;Pyn 接受负载,然后另行把它变成表单上一次以它指定的员工为名的提交,并把结果记录在 webhook 的日志中。创建 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 已丢弃 某个键不对应表单上的任何字段,或某个值的类型与字段不符。

每个被丢弃的负载还会在通知中生成一条通知;反复犯同一个错误的调用方只会更新同一条通知。

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

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