Webhook とは?
Webhook を使用すると、特定のシステム アクション が発生したときに、提供された URL への呼び出しを通じて通知を受け取ることができます。Webhook は「URL コールバック」または「HTTP プッシュコール」とも呼ばれます。URL は SSL を使用し、HTTPS で始まる必要があります。Webhook アクション
Webhook で利用可能なアクションを確認します。
Ayrshare Webhook を理解する
Webhook は特定のアクションによって分類され、Primary Profile または User Profile レベルで登録 されます。Primary または User Profile への更新は、まず User Profile 用に登録された Webhook に送信されます。User Profile に登録された Webhook がない場合、更新は Primary Profile に登録された Webhook に送信されます。 たとえば:- User Profile に登録された Social Action Webhook があり、TikTok のリンクを解除した場合、User Profile 用に登録された Social Action Webhook URL が呼び出されます。Primary Profile の Webhook は呼び出されません。
- User Profile が TikTok のリンクを解除し、登録された Social Action Webhook がないが、Primary Profile に登録された Webhook がある場合、Primary Profile 用に登録された Social Action Webhook URL が呼び出されます。
Webhook を登録する
エンドポイント URL とアクションタイプを POST/hook/webhook エンドポイントに提供して Webhook を登録します。アクションが発生すると、提供された URL に HTTP POST メッセージが送信されます。
たとえば、スケジュール投稿のステータス通知を受け取るために URL を登録します。
Webhook エンドポイント URL はリダイレクトを使用してはならず、最終的な宛先 URL である必要があります。
Primary Profile の Webhook のみを登録した場合、User Profile は自動的に Primary Profile の Webhook を継承します。
各 User Profile に一意の Webhook を持たせるには、User Profile ごとに Webhook を登録する必要があります。
Webhook が
HTTP POST を受信した後、サーバーは呼び出しを成功としてマークするために、HTTP ステータス 200 で応答する 必要があります。サーバーが 15 秒以内に応答しない場合、その試行は失敗として記録され、再試行されます。リクエストを受信したらすぐに応答し、処理は非同期で行ってください — タイムアウトは拒否ではないため、ハンドラーが処理を完了しても遅れて応答した場合、再試行により 2 回処理することになります。Webhook の再試行
失敗した配信が再試行されるかどうかは、どのように失敗したかによって決まります。すべての再試行は同じhookId を持ちます。ペイロードは試行ごとに再生成されるため、timeStamp とその署名は異なる場合があります。
再試行される — 一時的な失敗。 429、408、425 のレスポンス、あらゆる 5xx、タイムアウト、接続の切断は、約 1 時間にわたって最大 9 回の配信試行が行われます（初回送信と 8 回の再試行）。それでも失敗が続く場合は、約 5 分後、30 分後、2 時間後、12 時間後という減衰スケジュールで再度配信が試みられます。そのため、元のイベントから約 16 時間後まで配信が届く可能性があります。
再試行されない — 拒否。 400、401、403、404、410 などその他の 4xx レスポンスは、最初の試行で最終的なものとして扱われます。これらはリクエスト自体が拒否されたことを示しており、繰り返しても結果は変わりません。
配信セマンティクスと冪等性
Ayrshare は Webhook を 少なくとも 1 回 配信します。時折の重複は正常な動作であり、欠陥ではありません — すべての受信側は冪等性を恒久的な特性として備える必要があります。 重複は 2 種類の異なる形で到着し、それぞれに異なるキーが必要です:hookId はイベントの 1 件の配信 を識別します。同じ配信のすべての再試行で同一であるため、これに基づいてクレームすることで再試行を安全にできます — しかし、同じ根底のイベントが新しい通知として届く場合には 新しい hookId が付くため、hookId 単独ではそのケースを認識できません。
推奨される受信側パターン:
- まず応答する。 即座に
2xxを返し、その後非同期で処理します。タイムアウトは拒否ではありません — 処理を完了しても遅れて応答した場合、イベントは再送されます。 hookIdをアトミックにクレーム します。リクエストが到着した瞬間に、ユニーク制約、INSERT ... ON CONFLICT DO NOTHING、またはSET NXを使用します — 読み取ってから書き込むチェックは 使用しないでください。2 つの試行が同時に到着することがあり、チェックしてから動作するガードは両方を通してしまいます。- 独自のキーもクレーム します。ペイロードから構築することで、新しい
hookIdを持つ 2 回目の通知でも認識できるようにします。messagesの場合、idとsubActionの組み合わせがよく機能します。 - その後で 処理を行います。両方のクレームを、再試行ウィンドウと後の再通知をカバーするのに十分な期間保持します。再試行は約 16 時間後まで届く可能性があるため、クレームは少なくとも 24 時間保持してください。それより早く期限切れになるクレームは遅延した再試行を認識できず、同じイベントを 2 回処理することになります。
ペイロードの
id はすべてのイベントタイプで単独では一意ではありません — 同じメッセージ ID が編集やリアクションをまたいで再現されますし、messageRead ペイロードには id が含まれません — そのため、単独で使用するのではなく subAction と組み合わせてください。配信メタデータヘッダー
すべての配信には、その特定の送信を識別する 2 つのヘッダーが含まれており、オリジナルと再試行を区別できます:X-Ayrshare-Delivery-Attempt は最初の送信では 0 で、再試行のたびに 1 ずつ増加します。したがって、0 より大きい値は、この配信を少なくとも 1 回はすでに送信していることを意味します。固定された値の集合ではなく、無制限のカウンターとして扱ってください — 再試行回数は運用上の詳細であり、変更される可能性があります。X-Ayrshare-Delivery-Id は各試行に一意です — サポートに問い合わせる際にこれを伝えると、正確な配信レコードを特定できます。
これらは 送信 を識別します。hookId は イベント を識別します。重複排除は配信 ID ではなく hookId で行ってください — 配信 ID は設計上すべての試行で異なるため、そこで判定すると重複として認識されるものは何もなくなります。
Webhook セキュリティ
HMAC 認証を HTTP リクエストとして設定することで、追加のセキュリティを追加することを選択できます。これはしばしばリプレイ攻撃を防ぐために行われます。Ayrshare は HMAC-SHA256 を使用してメッセージのボディをハッシュ化し、それと UNIX タイムスタンプを POST のヘッダーに含めます。X-Authorization-Content-SHA256 と POST ボディの HMAC-SHA256 を比較することで POST を検証できます。署名シークレットはプロファイル全体で共通です — 1 つの User Profile につき 1 つのシークレットがあり、そのプロファイルのすべての webhook アクションで使用されるため、1 つのアクションに設定するとそのプロファイルのすべてのアクションでシークレットが変更されます。マルチプロファイルアカウントでは、プロファイルごとに個別のシークレットを管理します(Profile-Key ヘッダーでプロファイルを指定します)。