62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
---
|
|
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
|
|
```
|