Webhook response

← Webhook response

Ashterix

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

Webhook response

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.

Request

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

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.

Immediate response

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

Result delivery

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:

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

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).

A callback endpoint response with a status outside 2xx is treated as a delivery failure and is logged.

Versions 9.2.0–10.0.5

In these versions all client headers, including the RPC token, were forwarded to the callback. See Fixed issues.

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.

Algorithm

  1. Receive a request with $rpc.callback and validate the URL.
  2. Immediately return {"async": true, "callback": "<url>"} to the client.
  3. After the response has been sent, execute the method.
  4. Send the JSON-RPC response as a POST request to the callback URL.

Callback delivery errors are not reported in the immediate response.