Webhook API
Webhookは1つのフォームに属します。別のシステムがベアラーシークレットを付けて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にはフォームのフィールドごとに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です。
処理のルール
Section titled “処理のルール”- Webhookは1人の従業員につき最大1回だけ送信します。ある対象者の送信が完了すると、同じ
subject_idに対するそれ以降のペイロードはalready-submittedとして破棄されます。同じ人から繰り返し回答が必要なフォームでは、その回答にWebhookを使えません。 - ペイロードは全体として受け付けられるか、まったく受け付けられないかのどちらかです。必須フィールドの欠落や型の違う値があると、部分的な送信を記録するのではなく、ペイロード全体が破棄されます。
- Subjectが設定されていないフォームは何も受け付けません(
no-subject)。 - 受け付けられた送信は、他の送信と同じように振る舞います。フォームのActivityサイドパネルとエクスポートに表示され、BuddyやMentorの値を従業員に書き込み、そのフォームにForm Submissionトリガーを持つオートメーションを開始します。
ログのコード
Section titled “ログのコード”すべてのペイロードは、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つの通知を更新し続けることになります。
シークレット
Section titled “シークレット”| 操作 | 効果 |
|---|---|
| Create Secret | シークレットを持たないWebhookにシークレットを発行します。シークレットのないWebhookは何も受け付けません。 |
| Replace Secret | 新しいシークレットを発行します。古いものはすぐに使えなくなります。 |
シークレットは一度だけ表示され、あとから読み出すことはできません。どちらの操作にもAdminが必要です。
- Webhookを作成する:アプリでの手順についてです。
- フォームフィールドの種類:各フィールドが受け付ける値についてです。
- 通知:破棄されたペイロードが表示される場所です。