Handle synchronous callbacks

A synchronous callback requires the receiver to return a structured result within one HTTPS request. Configure it separately from asynchronous events. Selecting a long connection for events does not change synchronous callback transport.

You can configure token.agent.action.v1 and send synthetic Sandbox tests. Actual TOKEN business calls are not available yet. Saved configuration or a successful test does not prove production use.

Configure and test

1. Select the callback type under the current Sandbox Application → Developer integration → Events and webhooks → Callback configuration.
2. Configure a public HTTPS receiver, complete endpoint verification, and prepare signature validation, Verification Token and decryption according to current settings.
3. Save, send one synthetic test and inspect the separate callback result and receiver records.

If saving fails, follow configuration recovery. Recover configuration separately from checking an already sent test; recovery does not automatically send another test.

Asynchronous event and synchronous callback sets are saved independently; preserve the other complete set when changing one. A changed URL requires verification again. A test may execute receiver logic, so use an isolated test handler. Test requests carry X-GV-Test-Delivery: true.

Receive the request

Validate the signature, token and encrypted body according to current configuration, then validate the request Schema, Application and environment. After removing transport security fields, the envelope looks like this; all identifiers are synthetic.

{
  "schema_version": "1",
  "request_id": "callback-example-001",
  "callback_type": "token.agent.action.v1",
  "application_id": "application_opaque",
  "environment": "sandbox",
  "data": {"action": "check"}
}

Field	Type	Required	Description
schema_version	string	🔴 Required	Currently "1"
request_id	string	🔴 Required	Echo unchanged; prevent duplicate effects
callback_type	string	🔴 Required	token.agent.action.v1
application_id, environment	string	🔴 Required	Match the receiver Application and environment
data	object	🔴 Required	Application-defined JSON, at most 64 KiB

Do not replace the request identifier with an asynchronous event_id or lease ACK. See Receive webhooks for signature, encryption and credential retrieval.

Return a result

Return application/json within five seconds. The entire response must not exceed 64 KiB. Its envelope contains exactly these five fields; duplicate fields, unknown fields, a mismatched request identifier or a non-object result are rejected.

{
  "schema_version": "1",
  "request_id": "callback-example-001",
  "callback_type": "token.agent.action.v1",
  "status": "completed",
  "result": {"accepted": true}
}

Field	Type	Required	Description
schema_version	string	🔴 Required	Exactly "1"
request_id	string	🔴 Required	Must exactly match the request
callback_type	string	🔴 Required	Must exactly match the request
status	string	🔴 Required	completed or rejected
result	object	🔴 Required	Application-defined JSON object

A 2xx response without a valid result does not complete the callback.

Timeouts and unknown results

Each request identifier is attempted once. The platform never automatically retries an external effect. A timeout, disconnect or 503 can mean that processing occurred but its result was lost. Reconcile the original request_id with your receiver rather than retrying with a new identifier.

Submitting the same request identifier returns 409 without executing the effect again. Use a new identifier only after reconciliation and an explicit decision to start a new test. The receiver must still prevent duplicate business effects.

Situation	Action
Receiver URL changed or verification failed	Verify the actual receiver for the current Application before saving
Signature, token or decryption failed	Reject the request, check current credentials and preserve safe diagnostics
Result fields, types or identifiers do not match	Correct the response and reconcile the original request identifier
Timeout, disconnect or 503	Reconcile the original result before explicitly starting another test
409, request identifier already used	Read the original result; explicitly create a new identifier only for a new test

Next: Receive events over a long connection · Event catalog · Support and diagnostics

The X-GV-Callback-ID header matches the request identifier. Do not log the signature, token, encrypted body or full business payload.