イベントと Webhook
Edge は何かが変わるたびに イベント を記録します。deployment の準備完了、ドメインの検証、 訪問者のフォーム送信、他サービスによるフックの呼び出しなどです。Webhook はこれらのイベントを Edge の外へ運び、フックは他サービスのイベントを Edge に取り込みます。
イベントは変更と一緒に保存される
Edge は、変更そのものと同じデータベーストランザクションでイベントを書き込みます。deployment が ready になったなら deployment.ready イベントが存在し、書き込みが失敗したならどちらも存在 しません。起きなかったことが通知されることはなく、プロセスが悪いタイミングで止まったせいで、 起きたことが通知されないこともありません。
配信は at least once
ネットワークは途中で失敗します。エンドポイントがイベントを処理しても、その応答が届かない ことがあります。その場合 Edge は再送します。そのため配信は exactly once(ちょうど 1 回)では なく at least once(少なくとも 1 回) であり、再送はすべて同じ webhook-id を持ちます。 処理済みの id を記録する受信側は、at least once の配信の上で exactly once の 処理 を実現 できます。これはほぼすべての Webhook システムが提供する契約であり、Edge が採用する形式である Standard Webhooks もこれを前提に設計されています。
Edge は順序も保証しません。ready の最初の試行が失敗した場合、deployment.promoted が、 それより前に起きた deployment.ready より先に届くことがあります。timestamp を使うか、 イベントをきっかけとして API から現在の状態を読み取ってください。
フックは再送の重複を除く
受信側では役割が逆になります。Stripe、GitHub、LINE が再送し、Edge が受信側になります。各フックは 冪等キーごとに 受信記録(receipt) を持ち、他の処理より先にそれを確保します。そのため、同じ イベントの 2 つのコピーが同時に届いても、両方が通ることはありません。再送には 200 が返り (送信元は成功とみなして再送をやめます)、イベントの発行や promote が二度行われることは ありません。
フォームのデータに追加の承認が必要な理由
ほとんどのイベントは Edge 自身について説明するものです。form.submitted と hook.received は、 他の人が送った内容(名前、メールアドレス、注文の詳細など)を運びます。これらは データイベント です。
*には決して含まれないため、広い範囲のサブスクリプションから誤って漏れることはありません。- フォームの送信を転送するには、admin だけが持つ
form.forwardに加えて、明示的な確認が 必要です。Edge のエージェントツールはフォームの送信内容をまったく読めません。Webhook はそれが Edge の外に出る唯一の経路であるため、その作成は相応の判断として扱われます。
コンバージョンは約 1 分遅れて届く
goal.converted は他のイベントとは仕組みが異なります。コンバージョンは Edge の変更ではなく、 ゴールのルールに一致した訪問であり、そのルールはアナリティクスのデータに対して評価されます。そのため Edge はおよそ 1 分ごとに、サブスクリプションが選んだゴールについてだけ新しいコンバージョンを探します。 誰も購読していないゴールにはコストがかかりません。各コンバージョンには固定のイベント ID があるため、 二度探しても二度送られることはありません。データイベントと同じく * には含まれません。 コンバージョンごとにひとつ送られるため、含めるとデプロイ通知だけが欲しい受信側にイベントが 殺到してしまうからです。
関連するイベントをまとめる
各イベントの subject.id は対象(ひとつの deployment、ひとつの送信、ひとつのフックの受信記録) を示し、distribution_id はサイトを示します。エージェントプラットフォームなどの受信側は、 これらをキーにして、送信ごとまたはサイトごとにひとつの会話を保てます。