SuperSaaSのWebhook

SuperSaaSで利用できるWebhook
Webhookの認証処理
Webhookのメソッド指定
WebhookのRESTフック
1. Webhookの作成
2. Webhookの削除

SuperSaaSで利用できるWebhook

アプリやサービスで発生した処理がリアルタイムにHTTPプロトコルでプッシュ通知されるウェブフックがSuperSaaSでも提供されています。

例えば、予約が登録されるという処理が発生した瞬間、登録されたことと、その内容がリアルタイムでHTTPを用いて指定先に通知することができますので、その情報を受け取って処理するシステムの構築が可能になります。

システムをフルスクラッチするのも結構なコストになりますので、ウェブフックを用いた既存のシステムどうしを連動連携できるサービスを利用する方が手軽かもしれません。
「Make (旧Integromat)」や「Zapier」、「Integrately」、「Pipedream」などがSuperSaaSに対応しています。

SuperSaaSで現在提供されているWebhookのトリガーコード（データがプッシュ通知される起因コード）は9種類で、それぞれにイベント（起因の概略）、ロール（誰が起因したか）、ステータスフィールド（起因となった処理内容）が通知される内容となります。

Webhookのトリガー
トリガーコード	トリガー名	説明
U	New user	新規にユーザー登録されたことが起因
M	Changed user	ユーザー情報が更新されたことが起因
N	New appointment	予約が新規登録されたことが起因
C	Changed appointment	予約が更新されたことが起因
R	New stand-alone form	フォームから新規のデータが送信されたこと起因
F	Updated stand-alone form	フォームから送信されたデータ内容が更新されたことが起因
S	Send mail	SuperSaaSからシステムメールが発信されることが起因
O	Reminder /Follow-up	リマインダー、もしくは、フォローアップメールが発信されることが起因
P	Purchase	ショップで購入があったことが起因

トリガーは1文字のトリガーコードとして通知されます。
（およそ、トリガー名だとデータ的にも冗長になるためと思われます）

Send mailとReminder、Follow-upのWebhookを用いる場合は注意が必要
これらのWebhookはシステムよりのメール発信前に、その処理をWebhookがインターセプトする形になり、システムよりのメールが発信されなくなります。
つまり、Send mailとReminder、Follow-upのWebhookを用いる場合は、自前で通知処理を構築する必要があります。これは、システムとWebhookの2重の通知処理を回避するためのものと思われます。

API利用時の留意点
デフォルトではAPIによる処理はWebhookトリガーの対象になりません。
たとえば、APIで予約登録を行ってもNew appointmentがトリガーされない状態です。
APIでもWebhookをトリガーしたい場合は、そのAPIにWebhookをトリガーするためのパラメータwebhook=trueを付与する必要があります。

Webhookのイベント
親トリガー名	イベント	説明
New user	new	新規にユーザー登録された
Changed user	new、change、delete	ユーザー情報が編集（新規登録、情報更新、登録削除）された
New appointment	create	新規に予約が登録された
Changed appointment	create、edit、place、pending、destroy、restore、approve、revert	予約が編集（新規登録、予約更新、予約保留、予約削除、予約復元、予約承認、予約取り消し）された
New form	new	新規にフォームからデータが送信された
Changed form	new, change, delete, restore	フォームで送信されたデータ内容が編集（新規送信、内容更新、内容削除、内容復元）された
Reminder / Follow-up	reminder、follow_up	リマインダー通知、もしくは、フォローアップ通知が発信された
Purchase	purchase	ショップで購入があった

Send mailトリガーを概略分別できるイベントは設定されていないようです。

Webhookのロール
ロール	説明
0	誰が起因か不明（ログインしていない状態でトリガーされた）
1	誰が起因か特定不可（共有パスワードでログインしてトリガーされた）
2	誰が起因か特定不可（IPアドレスでの利用制限で提供されている状態でトリガーされた）
3	「ユーザー」によってトリガーされた
4	「superuser」によってトリガーされた
5	「管理者」によってトリガーされた
7	人ではなく、システムあるいは、ペイメントゲートウェイによりトリガーされた

ロールもトリガー同様に、説明のままだと冗長なデータとなり得ますので、数字の形で通知されます。

ウェブフックでプッシュ通知されるステータスフィールドには、そのトリガーごとに関連するフィールド全ての情報が内包され、さらに処理にフォームが付随する場合はそのフォームデータも全て含まれています。
実際にどういったデータ内容で通知されるかは、SuperSaaSのWebhook管理画面でテスト確認することが可能ですので、Webhookで通知される内容など実際に確認しながら検討することを推奨します。

システムメニューの連携からWebhookで管理画面に遷移できます。

なお、Webhook管理機能は無料版SuperSaaSでは利用できません。
有料版での機能ですが、アカウント新規登録後は任意のタイミングで試用することができます。
試用期間がシステムの設計や構築するにはあまりにも短く、とても確認とテストなど行うことは難しいですので、いくつかアカウントを作って渡りながらになりがちです。
実際にシステムを構築して活用を決めた際には有料版を用いるでしょうし、デベロップ関連は検討するだけでも時間がかかるので、試用期間にもうちょっと優遇が欲しい気がしますね。

Webhookの認証処理

Webhookを用いたシステムで認証が必要になる場合「ベーシック認証」と「ベアラーズトークン」を用いることができます。

指定するWebhookエンドポイントのURLの頭に＠を挟んで認証情報を付与します

例：ベーシック認証
https://ユーザーネーム:パスワード@送信先エンドポイントURL/endpoint

例：ベアラーズトークン
https://bearer:トークン@送信先エンドポイントURL/endpoint

Webhookのメソッド指定

Webhookを指定のHTTPメソッドで送信することもできます。
PUTやHEADメソッドなど指定可能です。

指定するWebhookエンドポイントにクエリ_methodを追加することで指定できます

例：ベーシック認証
https://送信先エンドポイントURL/endpoint?_method=メソッドの種類

WebhookのRESTフック

SuperSaaSではシステムによる管理やWebhookを用いた外部の連携サービス以外にも、WebhookをAPI経由で制御するメソッドが用意されています。

www.supersaas.com/api/hooks

Webhookの作成

APIに以下のパラメータをPOSTメソッドで送ることでWebhookを作成できるようです。

Webhook作成用フィールド
（物理名）論理名	概要
（account）アカウント名	SuperSaaSのアカウント名です。 (メールアドレスではありません)
（api_key） API Key	API利用認証用のAPI Keyです。
（event）トリガーコード	イベントとありますが、1文字のトリガーコードを指定するようです。
（parent_id）対象ID	トリガーにより異なりますが、対象となるIDを指定します。（スケジュール関連ならスケジュールID、フォーム関連ならフォームID、ユーザー関連など他の場合はSuperSaaSのアカウントIDを指定するようです）
（target_url）対象ID	トリガーにより異なりますが、対象となるIDを指定します。（スケジュール関連ならスケジュールID、フォーム関連ならフォームID、ユーザー関連など他の場合はSuperSaaSのアカウントIDを指定するようです）

最近追記された仕様なのですが、まだ読んだだけで試せてない状況なので、ちょっと理解が追いつかないです。
eventとありますがトリガーだし、イベントやステータスフィールドはどこからとってくるのかとか……
公式サイトのドキュメントではparent_idに指定するIDは、トリガーコードがU、M、H、 Pの場合アカウントIDを……とあるのですが、Hとかトリガーコードに無いし、、、、

実際にテストして挙動を確かめながらがベターのようですし、思い込みで開発するのは危険なので、ビジネス利用の場合などはサポートに仕様を確認して言質取っておいた方が安心かもです。

この辺りのAPIは時間のある時に試してみようと思いますので、現状は参考程度に読み流して機になる方は公式サイトの記述を熟読くださいm(__)m

【2024-04-01　追記】
Webhook作成APIをちょっと試してみました。

eventにN、parent_idにアカウントIDを指定してAPIを使用すると、ちゃんと新規ユーザーのWebhookが登録されました。

そこで、謎のトリガーコードHをeventの値にしてAPIを実行すると……

メールの送信のWebhookが登録されました。

なら、公式の紹介ページでトリガーコードがSであるはずのメールの送信をAPIから登録しようとすると……
レスポンスのステータスコード422となってAPI実行に失敗したようです。
ちなみに、eventにS、parent_idにアカウントIDを指定しています。
うーん、公式ドキュメントのタイポなんだろうか（＾＾；）ちょっと様子見かな……

【2024-04-04　追記】
一通りステータスコードを試した結果です。
422が返ってきて動かないトリガーもありますが、現状としての参考までに。

Webhookの削除

APIに以下のパラメータをDELETEメソッドで送ることでWebhookを削除できるようです。

Webhook削除用フィールド
（物理名）論理名	概要
（id） WebhookID	WebhookのIDです。
（parent_id）対象ID	作成したときに指定したparent_id。
（account）アカウント名	SuperSaaSのアカウント名です。 (メールアドレスではありません)
（api_key） API Key	API利用認証用のAPI Keyです。

Developer | Webhooks

Set up webhooks that inform other processes about events happening on your account

（物理名）論理名	概要
（account）アカウント名	SuperSaaSのアカウント名です。 (メールアドレスではありません)
（api_key） API Key	API利用認証用のAPI Keyです。
（event）トリガーコード	イベントとありますが、1文字のトリガーコードを指定するようです。
（parent_id）対象ID	トリガーにより異なりますが、対象となるIDを指定します。（スケジュール関連ならスケジュールID、フォーム関連ならフォームID、ユーザー関連など他の場合はSuperSaaSのアカウントIDを指定するようです）
（target_url）対象ID	トリガーにより異なりますが、対象となるIDを指定します。（スケジュール関連ならスケジュールID、フォーム関連ならフォームID、ユーザー関連など他の場合はSuperSaaSのアカウントIDを指定するようです）