エンドポイント

use OpenEmail\Constants\WebhookEvents; $endpoint = $client->webhooks->create([    'url' => 'https://acme.com/hooks/mail',    'eventTypes' => [WebhookEvents::EMAIL_SENT, WebhookEvents::EMAIL_BOUNCED],    'description' => 'Billing service',]); file_put_contents('.openemail-webhook-secret', $endpoint['secret']); $client->webhooks->list();$client->webhooks->get($endpoint['id']);$client->webhooks->update($endpoint['id'], ['enabled' => false]);$client->webhooks->test($endpoint['id']); foreach ($client->webhooks->listDeliveries($endpoint['id'], limit: 1) as $latest) {    $client->webhooks->getDelivery($endpoint['id'], $latest['id']);    $client->webhooks->replayDelivery($endpoint['id'], $latest['id']);} $rotated = $client->webhooks->rotateSecret($endpoint['id']);file_put_contents('.openemail-webhook-secret', $rotated['secret']); $client->webhooks->delete($endpoint['id']);

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

list は OpenEmail\Result\Page を 1 つ返し、listAll はすべてのエンドポイントを 1 つの配列で返し、iterate はエンドポイントを 1 つずつ yield する Generator を返します。create と update は API の名前をキーとする 1 つの配列としてボディを受け取り、エンドポイントはすべて camelCase のキーを持つ配列として返ります。

OpenEmail\Constants\WebhookEvents はすべてのイベントを定数として定義し、WebhookEvents::values() がそれらを一覧にするため、リクエストなしで一覧を表示できます。webhooks->listEvents は同じ名前をそれぞれのラベル付きで返し、さらにエンドポイントに課される上限を maxEndpoints、maxAddresses、maxDomains で返します。イベントはこの API のイベントではなく、メールボックスのイベントです。email.received はアプリに届いたメールで発火し、email.sent はコンポーザーが送ったメッセージで発火します。購読は、自分の API のトラフィックを監視することと同じではありません。

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

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');echo $result['delivery']['status'], ' ', $result['delivery']['responseCode'] ?? 'no response', PHP_EOL; foreach ($client->webhooks->iterateDeliveries('whe_3f9c2a7b1e4d8f60a5c7b92d') as $delivery) {    echo $delivery['eventType'], ' ', $delivery['status'], ' ', $delivery['responseCode'] ?? '-', ' ', $delivery['error'] ?? '', PHP_EOL;}

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

$detail = $client->webhooks->getDelivery('whe_3f9c2a7b1e4d8f60a5c7b92d', 'whd_8c1e4a7f2b9d3e6a0c5f1b28');echo json_encode($detail['payload'], JSON_THROW_ON_ERROR), PHP_EOL;echo $detail['responseBody'] ?? 'no answer', ' ', $detail['replayRefusal']['code'] ?? 'replayable', PHP_EOL; $replay = $client->webhooks->replayDelivery('whe_3f9c2a7b1e4d8f60a5c7b92d', 'whd_8c1e4a7f2b9d3e6a0c5f1b28');echo $replay['delivery']['status'], ' ', $replay['delivery']['responseCode'] ?? 'no response', PHP_EOL;

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

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

camelCase のキーを持つ配列。get、list、update は secret を除いた同じ形を返します。

$failed = $client->webhooks->listWorkspaceDeliveries(status: 'failed', since: new \DateTimeImmutable('-1 day')); foreach ($failed as $delivery) {    echo $delivery['endpointId'], ' ', $delivery['eventType'], ' ', $delivery['responseCode'] ?? '-', PHP_EOL;} $history = $client->webhooks->listActivity('whe_3f9c2a7b1e4d8f60a5c7b92d'); foreach ($history as $change) {    echo $change['type'], ' ', $change['actor']['label'] ?? 'OpenEmail', PHP_EOL;}

listDeliveries は 1 つのエンドポイントを、listWorkspaceDeliveries はすべてのエンドポイント、または endpointIds: で配列かカンマ区切りの 1 つの文字列として指定したものを読みます。どちらもコンソールの「配信」タブのフィルターである status:（delivered または failed）、since:、until: を受け取ります。listActivity と listWorkspaceActivity は監査ログを読みます。誰が何を作成、変更、切り替え、ローテーション、テスト、リプレイ、削除したかです。それぞれに、listAllDeliveries と iterateDeliveries のように listAll と iterate の版があり、ワークスペースのログのすべての行は endpointId を持ちます。webhooks->stats は、指定した期間について「分析」タブの数値を返します。