callbacks service draft

README.md

@@ -28,6 +28,7 @@ Financial services platform providing payment orchestration, ledger accounting,
 | Gateway TGSettle | `api/gateway/tgsettle/` | Telegram settlements with MNTX |
 | Notification | `api/notification/` | Notifications |
 | BFF | `api/edge/bff/` | Backend for frontend |
+| Callbacks | `api/edge/callbacks/` | Webhook callbacks delivery |
 | Frontend | `frontend/pweb/` | Flutter web UI |
 
 ## Development
@@ -70,7 +71,7 @@ make build-core       # discovery, ledger, fees, documents
 make build-fx         # oracle, ingestor
 make build-payments   # orchestrator
 make build-gateways   # chain, tron, mntx, tgsettle
-make build-api        # notification, bff
+make build-api        # notification, callbacks, bff
 make build-frontend   # Flutter web UI
 ```
 
@@ -98,3 +99,64 @@ make update            # Update all Go and Flutter dependencies
 make update-api        # Update Go dependencies only
 make update-frontend   # Update Flutter dependencies only
 ```
+
+### Callbacks Secret References
+
+Callbacks (`api/edge/callbacks`) supports three secret reference formats:
+
+- `env:MY_SECRET_ENV` to read from environment variables.
+- `vault:some/path#field` to read a field from Vault KV v2.
+- `some/path#field` to read from Vault KV v2 when `secrets.vault` is configured.
+
+If `#field` is omitted, callbacks uses `secrets.vault.default_field` (default: `value`).
+
+### Callbacks Vault Auth (Dev + Prod)
+
+Callbacks now authenticates to Vault through a sidecar Vault Agent (AppRole), same pattern as chain/tron gateways.
+
+- Dev compose:
+  - service: `dev-callbacks-vault-agent`
+  - shared token file: `/run/vault/token`
+  - app reads token via `VAULT_TOKEN_FILE=/run/vault/token` and `token_env: VAULT_TOKEN`
+- Prod compose:
+  - service: `sendico_callbacks_vault_agent`
+  - same token sink and env flow
+  - AppRole creds are injected at deploy from `CALLBACKS_VAULT_SECRET_PATH` (default `sendico/edge/callbacks/vault`)
+
+Required Vault policy (minimal read-only for KV v2 mount `kv`):
+
+```hcl
+path "kv/data/callbacks/*" {
+  capabilities = ["read"]
+}
+
+path "kv/metadata/callbacks/*" {
+  capabilities = ["read", "list"]
+}
+```
+
+Create policy + role (example):
+
+```bash
+vault policy write callbacks callbacks-policy.hcl
+vault write auth/approle/role/callbacks \
+  token_policies="callbacks" \
+  token_ttl="1h" \
+  token_max_ttl="24h"
+vault read -field=role_id auth/approle/role/callbacks/role-id
+vault write -f -field=secret_id auth/approle/role/callbacks/secret-id
+```
+
+Store AppRole creds for prod deploy pipeline:
+
+```bash
+vault kv put kv/sendico/edge/callbacks/vault \
+  role_id="<callbacks-role-id>" \
+  secret_id="<callbacks-secret-id>"
+```
+
+Store webhook signing secrets (example path consumed by `secret_ref`):
+
+```bash
+vault kv put kv/callbacks/client-a/webhook secret="super-secret"
+```