docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/functionality/callback/README.md
new file +62
ā0
1
+
# Webhook response
2
+
3
+
For long operations the client does not have to wait for the result. The special `$rpc.callback` parameter tells the server: accept the request, confirm it right away, and send the result to the specified URL once the method has been executed.
4
+
5
+
## Request
6
+
7
+
```json
8
+
{
9
+
"jsonrpc": "2.0",
10
+
"id": "order-42",
11
+
"method": "Orders.export",
12
+
"params": {
13
+
"id": 42,
14
+
"$rpc": {"callback": "https://client.example/rpc-callback"}
15
+
}
16
+
}
17
+
```
18
+
19
+
`callback` must be a full address with the `http` or `https` protocol. The address is checked immediately: if it is invalid or does not respond, the request returns a validation error.
20
+
21
+
## Immediate response
22
+
23
+
```json
24
+
{
25
+
"jsonrpc": "2.0",
26
+
"id": "order-42",
27
+
"result": {"async": true, "callback": "https://client.example/rpc-callback"}
28
+
}
29
+
```
30
+
31
+
## Result delivery
32
+
33
+
The method is executed **after** the immediate response has been sent (the `rpc.post_response` event). The full JSON-RPC response ā with `result` or `error` ā is sent as a POST request to the callback URL:
34
+
35
+
```json
36
+
{
37
+
"jsonrpc": "2.0",
38
+
"id": "order-42",
39
+
"result": {"orderId": 42, "status": "exported"}
40
+
}
41
+
```
42
+
43
+
The callback request has `Content-Type` and `Accept` set to `application/json` and a 10 s timeout (no more than 15 s in total). Only tracing headers are forwarded from the incoming HTTP request: `X-Request-Id`, `X-Correlation-Id`, `traceparent`, `tracestate`, `baggage`. The token and other client credentials are **not** forwarded, so configure authentication of the callback endpoint separately (for example, with a secret in the URL itself).
44
+
45
+
A callback endpoint response with a status outside 2xx is treated as a delivery failure and is logged.
46
+
47
+
:::info subtitle="Versions 9.2.0ā10.0.5"
48
+
In these versions **all** client headers, including the RPC token, were forwarded to the callback. See [Fixed issues](/docs/api/json-rpc-bundle/developers/known_issues/fixed).
49
+
:::
50
+
51
+
:::warning
52
+
Under PHP-FPM the method is executed after `fastcgi_finish_request()`, and the client does not wait. In other SAPIs the method is executed too, but the HTTP worker is busy until it finishes. For long methods you can enable detached execution ā `notification.process` in the [configuration](/docs/api/json-rpc-bundle/config).
53
+
:::
54
+
55
+
## Algorithm
56
+
57
+
1. Receive a request with `$rpc.callback` and validate the URL.
58
+
2. Immediately return `{"async": true, "callback": "<url>"}` to the client.
59
+
3. After the response has been sent, execute the method.
60
+
4. Send the JSON-RPC response as a POST request to the callback URL.
61
+
62
+
Callback delivery errors are not reported in the immediate response.