エンドポイント

endpoint = client.webhooks.create(  url: "https://acme.com/hooks/mail",  eventTypes: ["email.sent", "email.bounced"],  description: "Billing service") File.write(".openemail-webhook-secret", endpoint[:secret]) client.webhooks.listclient.webhooks.get(endpoint[:id])client.webhooks.update(endpoint[:id], enabled: false)client.webhooks.test(endpoint[:id])latest = client.webhooks.list_deliveries(endpoint[:id], limit: 1).items.firstclient.webhooks.get_delivery(endpoint[:id], latest[:id])client.webhooks.replay_delivery(endpoint[:id], latest[:id])rotated = client.webhooks.rotate_secret(endpoint[:id])File.write(".openemail-webhook-secret", rotated[:secret])client.webhooks.delete(endpoint[:id])

シークレットが返されるのは、rotate_secret を除けば create のときだけです。読み取りでシークレットが返ることはないので、何よりも先に保存してください。eventTypes を省略すると既定のセット、すなわち email.replied を除くすべての email.* イベントになります。email.replied、domain.*、suppression.*、file.*、form.* は、エンドポイントがそれらを明示した場合にのみ届きます。

OpenEmail::WEBHOOK_EVENTS はすべてのイベント名を持つ凍結された Hash なので、リクエストなしで一覧を表示でき、webhooks.list_events は同じ名前をそれぞれの説明文と、エンドポイントに課される上限とともに返します。イベントはこの API のイベントではなく、**メールボックス**のイベントです：email.received はアプリに届いたメールに対して発火し、email.sent はコンポーザーが送信したメッセージに対して発火します。購読することは、自分の API トラフィックを監視することとは違います。

file.uploaded はファイルが「ファイル」ページに追加されたときに、file.deleted はファイルが削除されたときに発火します。その data は fileId、filename、mimeType、sizeBytes、direction、to、threadId、messageId、そして uploadedAt または deletedAt を含みます。to はファイルが属するアドレスで、ワークスペース全体に属するファイルなら nil になります。

form.submitted は誰かがあなたのフォームのいずれかから登録したときに発火し、form.confirmed は本人が確認リンクを開いたか、あなたが承認したことで、確認待ちの登録がオーディエンスに加わったときに発火します。form.submitted の data は formId、formName、submissionId、email、status、answers、audienceIds、sourceUrl、submittedAt を含みます。form.confirmed の data は formId、formName、submissionId、email、audienceIds、link または approval のいずれかである via、そして confirmedAt を含みます。

result = client.webhooks.test("whe_3f9c2a7b1e4d8f60a5c7b92d")puts result.dig(:delivery, :status), result.dig(:delivery, :responseCode) client.webhooks.iterate_deliveries("whe_3f9c2a7b1e4d8f60a5c7b92d") do |delivery|  puts "#{delivery[:eventType]} #{delivery[:status]} #{delivery[:responseCode]} #{delivery[:error]}"end

test は署名付きの合成された email.sent イベントを POST し、試行が終わるまで待ちます。受信側が何を返しても通常どおり戻るため、呼び出しが例外を送出したかどうかではなく delivery[:status] で分岐してください。4xx は有益な答えです：URL には到達でき、拒否はあなた自身のハンドラー、多くの場合その署名チェックから来ています。

detail = client.webhooks.get_delivery("whe_3f9c2a7b1e4d8f60a5c7b92d", "whd_8c1e4a7f2b9d3e6a0c5f1b28")p detail[:payload], detail[:responseBody], detail[:replayRefusal] replay = client.webhooks.replay_delivery("whe_3f9c2a7b1e4d8f60a5c7b92d", "whd_8c1e4a7f2b9d3e6a0c5f1b28")p replay.dig(:delivery, :status), replay.dig(:delivery, :responseCode)

失敗し続ける配信は最大 8 回試行される。まず即時、その後 1 分後、5 分後、30 分後、2 時間後、5 時間後、10 時間後、さらに 10 時間後で、合計で約 27 時間半になる。繰り返すのは、繰り返す価値のある失敗だけである。応答なし、408、425、429、5xx がそれにあたる。再送は保存されたイベントを同じ id、type、createdAt、data で送り直すため、処理済みの id を捨てる受信側は、それを既知のイベントとして扱う。新しくなるのは署名だけである。

• —replay_delivery は 1 件のイベントを今すぐ送り、サーバーの応答を返します。配信済みの試行にも使え、リトライされることはありません。送信の前に、そのイベントの自動リトライのうちまだ始まっていないものは一時停止されます：再送が配信されればそれらはキャンセルされたままになり、失敗すれば予定どおり再開します。
• —その瞬間に同じイベントの自動リトライが送信中であれば、replay_delivery は何も送らず 409 retry_in_progress を送出し、同じイベントの別の再送がまだ送信中であれば 409 replay_in_progress を送出します。そのため、同じ瞬間に 2 回再送しても、受信側が同時に 2 通を受け取ることはありません。数秒待ってから get_delivery を読んでください。そのリトライや再送で配信される場合があります。再送は 1 件ずつです：失敗した配信をすべて再送する呼び出しはありません。
• —さらに、無効化されたエンドポイント（webhook_disabled）、エンドポイントがもう購読していないイベント（event_not_subscribed）やもう対象としていないイベント（event_out_of_scope）、保存されたイベントのない試行（delivery_not_replayable）にも 409 を送出します。get_delivery はこの結果を replayRefusal として事前に知らせます。

Symbol キーの Hash。get、list、update は secret を除いた同じ形を返します。

failed = client.webhooks.list_workspace_deliveries(status: "failed", since: Time.now - 86_400)p failed.items.map { |delivery| [delivery[:endpointId], delivery[:eventType], delivery[:responseCode]] } history = client.webhooks.list_activity("whe_3f9c2a7b1e4d8f60a5c7b92d")p history.items.map { |change| [change[:type], change.dig(:actor, :label)] }

list_deliveries は 1 つのエンドポイントを、list_workspace_deliveries はすべてのエンドポイントまたは endpoint_ids: で指定したものを読み、どちらもコンソールの「配信」タブのフィルターと同じ status:、since:、until: を受け取ります。list_activity と list_workspace_activity は監査ログを読みます：誰が何を作成・変更・無効化または有効化・ローテーション・テスト・再送・削除したか。それぞれに list_all_ と iterate_ の版があり、ワークスペースのログの各行には endpointId が付きます。webhooks.stats は、任意の期間について「分析」タブの元になる数値を返します。