Эндпоинты

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']);

create является ЕДИНСТВЕННЫМ случаем, когда секрет возвращается, не считая rotateSecret. При чтении он никогда не выдаётся, поэтому сохраните его прежде всего остального. Опустите eventTypes, чтобы получить набор по умолчанию: все события email.*, кроме email.replied. email.replied, domain.*, suppression.*, file.* и form.* доходят до эндпоинта, только если он их называет.

list возвращает одну OpenEmail\Result\Page, listAll возвращает все эндпоинты одним массивом, а iterate возвращает Generator, который выдаёт эндпоинты по одному. create и update принимают тело одним массивом с именами из API, и каждый эндпоинт возвращается как массив с ключами в 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, когда ожидающая подписка вступает в аудитории, потому что человек открыл ссылку подтверждения или потому что вы её одобрили. data у form.submitted содержит formId, formName, submissionId, email, status, answers, audienceIds, sourceUrl и submittedAt. data у form.confirmed содержит formId, formName, submissionId, email, audienceIds, via (равный link или approval) и 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 и ждёт завершения попытки. Он возвращается штатно, что бы ни ответил ваш приёмник, поэтому ветвитесь по $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, так что получатель, отбрасывающий уже обработанные идентификаторы, принимает его за уже известное событие. Новая только подпись.

• —replayDelivery отправляет одно событие сейчас и возвращает ответ вашего сервера. Работает и с доставленной попыткой и никогда не повторяется. Перед отправкой ещё не начавшиеся автоматические повторы этого события приостанавливаются: если повторная отправка доставлена, они остаются отменёнными, а если она не удалась, возобновляются по своему расписанию.
• —Если в этот момент отправляется автоматический повтор того же события, replayDelivery ничего не отправляет и выбрасывает 409 retry_in_progress, а пока ещё отправляется другая повторная отправка этого события, выбрасывает 409 replay_in_progress, поэтому ваш приёмник никогда не получит две копии одновременно, даже от двух повторных отправок, запущенных в один и тот же момент. Подождите несколько секунд и прочитайте getDelivery, поскольку тот повтор или та повторная отправка могут доставить событие. Повторная отправка работает по одному событию: нет вызова, который заново отправляет все неудачные доставки.
• —Он также выбрасывает 409 для выключенного эндпоинта (webhook_disabled), для события, которое эндпоинт больше не слушает (event_not_subscribed) или больше не охватывает (event_out_of_scope), и для попытки без сохранённого события (delivery_not_replayable). Каждый из них является 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 читает один эндпоинт, а listWorkspaceDeliveries все эндпоинты или те, что называет endpointIds:, в виде массива или одной строки через запятую, и оба принимают status: (delivered или failed), since: и until:, фильтры вкладки «Доставки» в консоли. listActivity и listWorkspaceActivity читают журнал аудита: кто что создал, изменил, переключил, ротировал, протестировал, отправил повторно или удалил. У каждого есть версии listAll и iterate, например listAllDeliveries и iterateDeliveries, а каждая строка журнала рабочего пространства несёт endpointId. webhooks->stats возвращает числа, стоящие за вкладкой «Аналитика», за выбранное вами окно.