Відповідь на webhook

Для довгих операцій клієнту не обов'язково чекати результату. Спеціальний параметр $rpc.callback каже серверу: прийми запит, одразу підтверди, а результат надішли на вказаний URL, коли метод виконається.

Запит

{
    "jsonrpc": "2.0",
    "id": "order-42",
    "method": "Orders.export",
    "params": {
        "id": 42,
        "$rpc": {"callback": "https://client.example/rpc-callback"}
    }
}

callback має бути повною адресою з протоколом http або https. Адреса перевіряється одразу: якщо вона невалідна або не відповідає, запит повертає помилку валідації.

Миттєва відповідь

{
    "jsonrpc": "2.0",
    "id": "order-42",
    "result": {"async": true, "callback": "https://client.example/rpc-callback"}
}

Доставка результату

Метод виконується після відправлення миттєвої відповіді (подія rpc.post_response). Повна JSON-RPC відповідь — з result або error — надсилається POST-запитом на callback URL:

{
    "jsonrpc": "2.0",
    "id": "order-42",
    "result": {"orderId": 42, "status": "exported"}
}

Запит на callback має Content-Type і Accept application/json, таймаут 10 с (не більше 15 с загалом). З вхідного HTTP-запиту пересилаються лише заголовки трасування: X-Request-Id, X-Correlation-Id, traceparent, tracestate, baggage. Токен та інші облікові дані клієнта не пересилаються, тож автентифікацію callback-endpoint налаштовуйте окремо (наприклад, секретом у самому URL).

Відповідь callback-endpoint зі статусом поза 2xx вважається помилкою доставки й пишеться в лог.

У цих версіях на callback пересилалися всі заголовки клієнта, включно з RPC-токеном. Див. Виправлені помилки.

Під PHP-FPM метод виконується після fastcgi_finish_request(), і клієнт не чекає. В інших SAPI метод теж виконається, але HTTP-воркер зайнятий до його завершення. Для довгих методів можна ввімкнути від'єднане виконання — notification.process у налаштуваннях.

Алгоритм

Отримати запит з $rpc.callback і провалідувати URL.
Одразу повернути клієнту {"async": true, "callback": "<url>"}.
Після відправлення відповіді виконати метод.
Надіслати JSON-RPC відповідь POST-запитом на callback URL.

Помилки доставки на callback у миттєвій відповіді не повідомляються.