SuperSaaSで利用できるWebhook
アプリやサービスで発生した処理がリアルタイムにHTTPプロトコルでプッシュ通知されるウェブフックがSuperSaaSでも提供されています。
例えば、予約が登録されるという処理が発生した瞬間、登録されたことと、その内容がリアルタイムでHTTPを用いて指定先に通知することができますので、その情報を受け取って処理するシステムの構築が可能になります。
「Make (旧Integromat)」や「Zapier」、「Integrately」、「Pipedream」などがSuperSaaSに対応しています。
SuperSaaSで現在提供されているWebhookのトリガーコード(データがプッシュ通知される起因コード)は9種類で、それぞれにイベント(起因の概略)、ロール(誰が起因したか)、ステータスフィールド(起因となった処理内容)が通知される内容となります。
トリガーコード | トリガー名 | 説明 |
---|---|---|
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文字のトリガーコードとして通知されます。
(およそ、トリガー名だとデータ的にも冗長になるためと思われます)
デフォルトではAPIによる処理はWebhookトリガーの対象になりません。
たとえば、APIで予約登録を行ってもNew appointmentがトリガーされない状態です。
APIでもWebhookをトリガーしたい場合は、そのAPIにWebhookをトリガーするためのパラメータwebhook=trueを付与する必要があります。
親トリガー名 | イベント | 説明 |
---|---|---|
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トリガーを概略分別できるイベントは設定されていないようです。
ロール | 説明 |
---|---|
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経由で制御するメソッドが用意されています。
Webhookの作成
APIに以下のパラメータをPOSTメソッドで送ることで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をちょっと試してみました。
そこで、謎のトリガーコードHをeventの値にしてAPIを実行すると……
メールの送信のWebhookが登録されました。
なら、公式の紹介ページでトリガーコードがSであるはずのメールの送信をAPIから登録しようとすると……
レスポンスのステータスコード422となってAPI実行に失敗したようです。
ちなみに、eventにS、parent_idにアカウントIDを指定しています。
うーん、公式ドキュメントのタイポなんだろうか(^^;)ちょっと様子見かな……
【2024-04-04 追記】
一通りステータスコードを試した結果です。
422が返ってきて動かないトリガーもありますが、現状としての参考までに。
Webhookの削除
APIに以下のパラメータをDELETEメソッドで送ることでWebhookを削除できるようです。
(物理名) 論理名 | 概要 |
---|---|
(id) WebhookID | WebhookのIDです。 |
(parent_id) 対象ID | 作成したときに指定したparent_id。 |
(account) アカウント名 | SuperSaaSのアカウント名です。 (メールアドレスではありません) |
(api_key) API Key | API利用認証用のAPI Keyです。 |
- Advance
- iframeで埋め込み活用
- 独自ドメインで活用
- SSLでの利用
- ホワイトラベル活用
- オンライン決済サービスの活用
- Paypalの設定
- Stripeの設定
- Squareの設定
- Mollieの設定
- ePayの設定
- PayUの設定
- Paystackの設定
- Mercado Pagoの設定
- その他の決済サービスを利用
- 他サービスとの連携
- 連携サービスの活用
- Make(旧Integromat)
- Zapier
- Pipedream
- Integrately
- SureTriggers
- ZoomやGoogle Meetとの連携
- SuperSaaSのWebhook
- SuperSaaSのAPI
- APIの基本
- アポイントAPI
- ユーザーAPI
- フォームAPI
- インフォメーションAPI
- プロモーションAPI
- APIの活用例