---
title: 外部Webhook受信
description: 予約システムや顧客管理のシステムから届いたデータで、友だちの情報欄を書き換えたり、タグを付けたりする画面です。
sidebar:
  order: 5
related:
  - /settings/webhooks
  - /messaging/automations
---

外部のサービスに、Lally の受け取り用の URL へデータを送ってもらうと、そのデータで友だちの情報を自動で更新します。たとえば予約システムで予約が確定したら、その友だちに「予約確定」のタグを付ける、といった使い方をします。受け取ったときは、自動応答の「イベント応答」で、トリガーを「外部Webhook受信」にしたルールも動きます。

送る側の設定には、システムの担当者の作業が要ります。この画面で作った URL と「signing secret」を、担当者に渡してください。

- メニュー: 左メニューの「設定」→「外部Webhook受信」
- 見られる人: オーナー・管理者・スタッフ。設定の機能と担当のアカウントの両方が「編集」のスタッフは、設定を作ったり変えたりできます
- 前もって: 左メニューの一番上で、設定するアカウントを選んでおくこと

## 外部Webhook受信画面の見方

![外部Webhook受信の上半分。新規設定・設定一覧・名前・slug・エンドポイント・signing secret・受信を有効にするに番号が付いている](/screenshots/ja/settings/inbound-webhooks.webp)

| 番号 | 項目 | 説明 |
| --- | --- | --- |
| ① | 新規設定 | 空の入力欄にします。「signing secret」は新しく作られます |
| ② | 設定一覧 | 作った設定です。押すと、その設定の受信ログに切り替わります |
| ③ | 名前 | 管理用の名前です。100 文字までです |
| ④ | [slug](/getting-started/glossary#slug) | 受け取り用の URL の最後に付く名前です。半角の英小文字・数字・ハイフンで 64 文字まで、最初と最後は英数字です。例: reservation-system。名前を英数字で入れると、slug にも自動で入ります |
| ⑤ | [エンドポイント](/getting-started/glossary#エンドポイント) | 外部のサービスに登録してもらう、受け取り用の URL です |
| ⑥ | [signing secret](/getting-started/glossary#signing-secret) | 送る側と共有する合言葉です。【再生成】で作り直します。作り直したら、送る側にも新しい値を渡してください |
| ⑦ | 受信を有効にする | 外すと、この URL ではデータを受け付けません |

![外部Webhook受信の下半分。field mapping JSON・作成する・受信ログに番号が付いている](/screenshots/ja/settings/inbound-webhooks-2.webp)

| 番号 | 項目 | 説明 |
| --- | --- | --- |
| ⑧ | field mapping JSON | 受け取ったデータのどの値を、友だちのどの情報に入れるかを書きます。下の[データの使い方を指定する方法](#データの使い方を指定する方法)をご覧ください |
| ⑨ | 作成する / 更新する | 入れた内容を保存します |
| ⑩ | 受信ログ | 「状態」「設定」「受け取ったデータ」「エラー」「受信日時」です。右上で「全設定」か設定ごとに切り替えます |

設定は選んでいるアカウントごとに分かれています。

## 設定の作成の手順

1. **新しい設定を始める**

    左メニューの「外部Webhook受信」で【+ 新規設定】を押します。

2. **名前と slug を入れる**

    「名前」と「slug」を入れます。「エンドポイント」に受け取り用の URL が出ます。

3. **データの使い方を書く**

    「field mapping JSON」に、受け取ったデータの使い方を書きます。書き方は下の[データの使い方を指定する方法](#データの使い方を指定する方法)をご覧ください。

4. **保存して渡す**

    【作成する】を押します。「設定を作成しました」と出たら、「エンドポイント」の URL と「signing secret」を、送る側の担当者に渡します。

## データの使い方を指定する方法

「field mapping JSON」には次の 4 つを書きます。値の場所は `$.reservation.status` のように、受け取るデータの中の位置で書きます。

| キー | 中身 |
| --- | --- |
| `friendLookup` | どの友だちを更新するかの探し方です。`type` に `friend_id`（友だち ID）、`line_user_id`（LINE ユーザー ID）、`metadata`（友だち情報の値）のどれかを書き、`path` に値の場所を書きます。`metadata` のときは、`metadataKey` に照らし合わせるキーを書きます |
| `metadata` | 受け取った値を、`key` に書いた名前で友だちの情報に保存します。「友だち情報欄管理」にない名前でも保存されますが、友だちの詳細には出ません |
| `friendAttributes` | 受け取った値を、「友だち情報欄管理」で作った欄に保存します。`attributeKey` に欄の「項目キー」を書きます。友だちの詳細にも出ます |
| `tags` | 条件に合ったときに、`tagId` のタグを付けます。`path` だけなら値が空でないとき、`equals` も書けばその値と同じときに付けます |

例: 予約の状態が「confirmed」になったら、タグを付け、次の来店日を友だち情報欄に入れる

```json
{
  "friendLookup": { "type": "line_user_id", "path": "$.customer.line_user_id" },
  "friendAttributes": [{ "attributeKey": "next_visit_at", "path": "$.reservation.start_at" }],
  "tags": [{ "tagId": "付けたいタグの ID", "path": "$.reservation.status", "equals": "confirmed" }]
}
```

初めに入っている見本の `tag_xxx` は仮の ID です。そのまま保存せず、付けたいタグの ID に書き換えてください。

友だちが見つからなかったときは、情報もタグも変わりません。`line_user_id` で探す設定なら、まだ友だち追加していない人の分を 24 時間取っておき、その間に友だち追加したときに入れます。

## 送る側にお願いすること

送る側にはデータを JSON で、受け取り用の URL へ POST してもらいます。併せて、次の 3 つのヘッダーを付けてもらいます。

| ヘッダー | 中身 |
| --- | --- |
| `X-Webhook-Timestamp` | 送った時刻（UNIX 時間の秒、10 桁）。Lally の時刻と 300 秒以上ずれていると受け付けません |
| `X-Webhook-Event-Id` | 1 回の送信ごとの ID。半角の英数字・`_`・`-` で 128 文字までです。同じ ID は 2 回処理しません |
| `X-Signature` | `v1.時刻.イベントID.本文` の文字列を、signing secret で HMAC-SHA256 の署名をした値（16 進数） |

署名が合わないデータや、時刻が古いデータは受け付けません。

## 使用例：予約システムで予約が確定したら、友だちにタグを付ける

予約が確定した友だちに「予約確定」のタグを付け、自動応答でお礼のメッセージを送れるようにする例です。

1. **タグを用意する**

    「タグ管理」で「予約確定」のタグを作り、タグの ID を控えておきます。ID は、そのタグの人数を押すと開く「友だちリスト」の URL で、「tagId=」のあとの文字列です。

2. **受け取りの設定を作る**

    左メニューの「外部Webhook受信」で【+ 新規設定】を押し、「名前」に「予約システム」、「slug」に「reservation-system」を入れます。

3. **データの使い方を書く**

    「field mapping JSON」に、上の例のように書きます。`tagId` には控えたタグの ID を入れます。

4. **保存して担当者に渡す**

    【作成する】を押し、「エンドポイント」の URL と「signing secret」を、予約システムの担当者に渡します。

5. **届いたか確認する**

    予約システムから最初のデータが届いたら、「受信ログ」で「状態」が「処理済み」になっているかを確認します。

## 困ったとき

| こんなとき | 理由と対処 |
| --- | --- |
| 「このslugは既に使われています」と出る | ほかの設定で使っている slug です。別の slug にしてください |
| 「URLに使う名前は、半角の小文字・数字・ハイフンで1〜64文字にしてください」と出る | slug は 1〜64 文字で、半角の英小文字・数字・ハイフンだけを使い、最初と最後は英数字にしてください。例: reservation-system |
| 「項目の対応の形式が正しくありません」と出る | 「field mapping JSON」の全体を、`{}` で囲んだ形にしてください。かっこや「"」の閉じ忘れのときは、「field mapping JSON の形式が正しくありません」と出ます |
| 受信ログの「状態」が「失敗」になる | 受け取ったデータを処理できませんでした。「エラー」の列を見て、送る側の担当者に伝えてください |
| 送る側で、受け付けられなかったと出る | 送る側の担当者に、返ってきた番号（HTTP の状態）を見てもらってください。404 なら、受信が有効になっているかと、URL が正しいかを確認します。403 なら、署名・時刻・イベント ID を確認します。400 なら、送るデータを JSON の形にしてもらいます。signing secret を作り直したときは、新しい値を渡してください |
| データは届いているのに、友だちが変わらない | `friendLookup` の探し方・`path`・照らし合わせる値と、設定したアカウントを確認してください。友だちが見つかっているときは、入れる値の `path`、友だち情報欄の項目キー、タグの条件も確認します。`line_user_id` で探す設定では、まだ友だち追加していない人の分は取っておかれ、友だち追加したときに入ります |