4.9.10. Вебхуки для пошти

Принцип роботи вебхуків наступний:

1. Ви створюєте вебхук, вибираєте події, при яких він повинен спрацьовувати, і вказуєте адресу, куди повинен надсилатися запит.
2. За вказаною адресою розміщуєте скрипт, який буде приймати та обробляти запит від вебхука (див. приклад скрипта).
3. Далі, коли в поштовій скриньці настає вибрана подія (наприклад, надходить новий лист), сервер автоматично надсилає запит скрипту за вказаною адресою.
4. Скрипт приймає запит і виконує дії відповідно до заданої в ньому логіки (наприклад, підключається до поштової скриньки і завантажує повний лист або надсилає сповіщення про новий лист у месенджер).

Що передається в запиті:

• Для будь-яких подій:
  • mailbox — адреса поштової скриньки.
  • uid — унікальний ідентифікатор листа.
  • tstamp — мітка часу події.
  • event — тип події:
    • new — новий лист у скриньці.
    • create — новий лист у папці.
    • flags-set — зміна прапорців або видалення листа.
  • folder — папка, в якій знаходиться лист.
  • flags — значення прапорців (\\Seen, \\Deleted тощо).
• Для подій нового листа:
  • from — адреса відправника.
  • to — адреса отримувача.
  • subject — тема листа.
  • snippet — превью тіла листа (повний текст можна отримати тільки безпосередньо через підключення до поштової скриньки).
  • message_id — глобально унікальний ідентифікатор листа.

1. Відкрийте розділ «Webhooks».
2. Натисніть «Створити вебхук».
3. Заповніть форму і натисніть «Створити»:
   • Назва — назва вебхука.
   • Поштові скриньки — для яких поштових скриньок повинен спрацьовувати вебхук.
   • URL — куди буде надсилатися запит (адреса в форматі https://example.com/webhook.php).
   • Перевіряти SSL — якщо увімкнено, запит буде надсилатися тільки якщо у сайту з URL є дійсний SSL-сертифікат.
   • Події — за яких умов спрацьовуватиме вебхук:
     • Новий лист у скриньці — при надходженні нового листа.
     • Новий лист у папці — при появі листа в будь-якій папці (переміщення, створення чернетки тощо).
       • Враховуються тільки дії всередині поштової скриньки. Надходження нового листа не вважається появою листа в папці.
     • Зміна прапорців — при зміні набору прапорців (прочитано, позначено тощо).
     • Видалення листа — при безповоротньому видаленні листа (переміщення до кошика не вважається видаленням).
4. Підтвердьте володіння сайтом з URL — у кореневому каталозі цього сайту розмістіть файл з назвою webhook-confirm.txt, в якому буде вказано ID вашого облікового запису.

Усі створені вебхуки відображаються у списку в розділі «Webhooks»:

У колонці «Токен» можна скопіювати секретний токен. Токен передається в заголовку X-Webhook-Token при надсиланні запиту на адресу з URL. З його допомогою скрипт, який обробляє запит, може переконатися, що запит був надісланий саме з нашого сервера.

У колонці «Останній запит» відображається код відповіді, дата і час надсилання останнього запиту.

Кнопка «Лог останнього запиту» відкриває вікно з детальною інформацією про 50 останніх запитів. У вікні виводиться інформація по кожному запиту: назва поштової скриньки, подія, що спрацювала, код відповіді, дата і час надсилання запиту, а також повторна спроба (якщо була).

За допомогою кнопки ⚙️ («Редагувати») можна змінити налаштування існуючого вебхука. Налаштування такі ж, як при створенні. Зверніть увагу, що при зміні адреси сайту в URL потрібно підтвердити володіння ним.

Приклад простого скрипта, який приймає запит від вебхука, обробляє його і зберігає отримані дані у вигляді рядка JSON у файл data.log:

<?php

// Вкажіть тут токен вашого вебхука, щоб перевіряти автентичність запитів від сервера
define('SECTRET_TOKEN', 'your_webhook_secret_token_here');

header('Content-Type: application/json; charset=utf-8');

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
	http_response_code(405);
	echo json_encode(['ok' => false, 'error' => 'Method Not Allowed'], JSON_UNESCAPED_UNICODE);
	exit;
}

$headers = getallheaders();
if (!isset($headers['X-Webhook-Token']) || $headers['X-Webhook-Token'] !== SECTRET_TOKEN) {
	http_response_code(401);
	echo json_encode(['ok' => false, 'error' => 'Incorrect webhook token'], JSON_UNESCAPED_UNICODE);
	exit;
}

$raw = file_get_contents('php://input');
if ($raw === false || $raw === '') {
	http_response_code(400);
	echo json_encode(['ok' => false, 'error' => 'Empty body'], JSON_UNESCAPED_UNICODE);
	exit;
}

$data = json_decode($raw, true);
if (json_last_error() !== JSON_ERROR_NONE) {
	http_response_code(400);
	echo json_encode(['ok' => false, 'error' => 'Invalid JSON: ' . json_last_error_msg()], JSON_UNESCAPED_UNICODE);
	exit;
}

$entry = [
	'ts'   => gmdate('c'),
	'ip'   => $_SERVER['REMOTE_ADDR'] ?? null,
	'ua'   => $_SERVER['HTTP_USER_AGENT'] ?? null,
	'data' => $data,
	'webhook_id' => $headers['X-Webhook-Id'] ?? null,
];

// JSONL: один запис = один рядок
$line = json_encode($entry, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) . PHP_EOL;
$ok = file_put_contents(__DIR__ . '/data.log', $line, FILE_APPEND | LOCK_EX);

if ($ok === false) {
	http_response_code(500);
	echo json_encode(['ok' => false, 'error' => 'Failed to write log'], JSON_UNESCAPED_UNICODE);
	exit;
}

http_response_code(200);
echo json_encode(['ok' => true], JSON_UNESCAPED_UNICODE);