コンテンツにスキップ
PynPyn

Webhook API

Webhookは1つのフォームに属します。別のシステムがベアラーシークレットを付けて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にはフォームのフィールドごとに1つのエントリーを入れ、フィールドのエイリアス(ラベルのキャメルケース)またはキーで名前を付けます。すべてのキーはフォーム上のフィールドを指していなければならず、すべての値はそのフィールドが受け付けられるものでなければなりません。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がアーカイブされている、またはベアラーシークレットが一致しません。これらのケースは区別されないため、エンドポイントを探られることはありません。

本文がJSONでないままエンドポイントに届いたリクエストや、Pyn側に障害が起きている間のリクエストには、通常の4xxまたは5xxが返ります。5xxは再試行できます。

Idempotency-Keyヘッダーを送ると、同じWebhookへの同じキーの再送は202で受け付けられ、それ以上は処理されません。同じキーを別のWebhookに送ると別の配信として扱われます。ヘッダーがなければ、すべての投稿が処理されます。配信を追跡する手がかりはログのeventIdです。

  • Webhookは1人の従業員につき最大1回だけ送信します。ある対象者の送信が完了すると、同じsubject_idに対するそれ以降のペイロードはalready-submittedとして破棄されます。同じ人から繰り返し回答が必要なフォームでは、その回答にWebhookを使えません。
  • ペイロードは全体として受け付けられるか、まったく受け付けられないかのどちらかです。必須フィールドの欠落や型の違う値があると、部分的な送信を記録するのではなく、ペイロード全体が破棄されます。
  • Subjectが設定されていないフォームは何も受け付けません(no-subject)。
  • 受け付けられた送信は、他の送信と同じように振る舞います。フォームのActivityサイドパネルとエクスポートに表示され、BuddyやMentorの値を従業員に書き込み、そのフォームにForm Submissionトリガーを持つオートメーションを開始します。

すべてのペイロードは、Webhookのログ(フォームのSettingsサイドパネル。ログ全体のCSVエクスポート付き)に1件のエントリーを残します。

コード 結果 意味
submitted 処理済み その識別子に対する送信を記録しました。
no-subject 破棄 フォームにWebhookのサブジェクトが設定されていません。
invalid-payload 破棄 本文を{ subject_id, fields }として解析できませんでした。メッセージにフィールドと理由が示されます。
unknown-subject 破棄 選んだソースシステムで、その識別子を持つ従業員がいません。
already-submitted 破棄 このWebhookはその識別子に対してすでに送信済みです。
ambiguous-fields 破棄 1つの名前が複数のフィールドに一致したか、1つのフィールドが2回(キーとエイリアスで)指定されました。
missing-fields 破棄 必須フィールドが指定されていません。
invalid-fields 破棄 キーがフォーム上のどのフィールドも指していないか、値の型がそのフィールドに合いません。

破棄された各ペイロードは通知にも通知を上げます。同じ間違いを繰り返す呼び出し元は1つの通知を更新し続けることになります。

操作 効果
Create Secret シークレットを持たないWebhookにシークレットを発行します。シークレットのないWebhookは何も受け付けません。
Replace Secret 新しいシークレットを発行します。古いものはすぐに使えなくなります。

シークレットは一度だけ表示され、あとから読み出すことはできません。どちらの操作にもAdminが必要です。