---
name: x-financial-callback
description: Use when a Hermes task for X-Financial must report progress or completion back to the backend through the single generic callback endpoint.
---

# X-Financial Callback

Use this skill for every X-Financial task that must notify the backend after Hermes finishes work.

## Callback contract

Send exactly one HTTP `POST` request to the callback URL provided in the task payload.

Use:

- Header: `Authorization: Bearer <callback_token>`
- Header: `Content-Type: application/json`
- Body:

```json
{
  "type": "task_type_from_input",
  "run_id": "agent_run_id_from_input",
  "status": "succeeded",
  "summary": "short human-readable summary",
  "payload": {}
}
```

## Rules

- Always preserve the incoming `type` and `run_id`.
- Execute the callback directly for server-dispatched tasks; do not ask the user for a second confirmation.
- Use `scripts/send_callback.py` for the actual HTTP request so large JSON bodies, quotes, and multilingual text are encoded safely.
- For normal tasks, prefer letting the script build the generic envelope for you via
  `--type`, `--run-id`, `--status`, and `--summary`; then the JSON file on stdin should contain only the
  task-specific business payload.
- Prefer sending a validated JSON file for non-trivial payloads:
  `python3 ~/.hermes/skills/domain/x-financial-callback/scripts/send_callback.py --url "$CALLBACK_URL" --token "$CALLBACK_TOKEN" < /tmp/x-financial-callback.json`
- Before sending a large payload, validate it with `python3 -m json.tool /tmp/x-financial-callback.json >/dev/null`.
- For large multilingual payloads, write `/tmp/x-financial-callback.json` with the `write_file` tool first.
  Do not generate helper Python source files or shell heredocs merely to build JSON.
- Use `status: "running"` only for optional progress updates.
- Use `status: "succeeded"` once when the task is complete.
- Use `status: "failed"` once when the task cannot be completed, and include an `error` string.
- Put task-specific business data only inside `payload`.
- Do not invent extra callback endpoints. X-Financial accepts Hermes callbacks through one shared endpoint only.
- If the callback fails, retry the same request up to 3 times before returning failure.

## Preferred command

```bash
python3 ~/.hermes/skills/domain/x-financial-callback/scripts/send_callback.py \
  --url "$CALLBACK_URL" \
  --token "$CALLBACK_TOKEN" \
  --type "$TASK_TYPE" \
  --run-id "$RUN_ID" \
  --status succeeded \
  --summary "short human-readable summary" \
  < /tmp/x-financial-callback.json
```