---
title: "Webhook API"
description: "フォームの受信Webhookについて：エンドポイント、ベアラーシークレット、subject_idとfieldsを持つJSON本文、冪等性キー、2種類のレスポンス、従業員1人につき1回のルール、そしてログに記録されるすべてのコード。"
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は1つのフォームに属します。別のシステムがベアラーシークレットを付けてJSON本文を投稿すると、Pynはペイロードを受け付け、その後に別の処理として、本文が指定する従業員のフォーム送信に変換し、結果をWebhookのログに記録します。アプリでの設定は[Webhookを作成する](https://support.pyn.ai/ja/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`にはフォームのフィールドごとに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` | 破棄 | キーがフォーム上のどのフィールドも指していないか、値の型がそのフィールドに合いません。 |

破棄された各ペイロードは[通知](https://support.pyn.ai/ja/notices/)にも通知を上げます。同じ間違いを繰り返す呼び出し元は1つの通知を更新し続けることになります。

## シークレット

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

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

## 関連ページ

- [Webhookを作成する](https://support.pyn.ai/ja/flows/forms/create-a-webhook/)：アプリでの手順についてです。
- [フォームフィールドの種類](https://support.pyn.ai/ja/flows/forms/reference-form-field-types/)：各フィールドが受け付ける値についてです。
- [通知](https://support.pyn.ai/ja/notices/)：破棄されたペイロードが表示される場所です。
