Valta Docs
Webhooks
Coming Q3 2026. Not available in beta.
Instead of polling GET /api/v1/agents/:id/runs, your server receives a signed HTTP POST each time a Valta event fires.
Events
| Event | Fires when |
|---|---|
agent.run.completed | An agent run finishes successfully |
agent.run.failed | An agent run fails |
agent.frozen | An agent is frozen |
agent.approval_required | An agent run is paused waiting for approval |
wallet.deposit | Funds are deposited into an agent wallet |
wallet.low_balance | A wallet drops below the configured threshold |
policy.violation | An agent attempts an action that violates policy |
audit.injection_detected | A prompt injection attempt is blocked |
Register a webhook
ts
await valta.webhooks.create({
url: 'https://your-server.com/valta-events',
events: ['agent.frozen', 'wallet.deposit', 'policy.violation'],
secret: process.env.VALTA_WEBHOOK_SECRET,
})
Verify and handle on your server
ts
app.post('/valta-events', (req, res) => {
const sig = req.headers['x-valta-signature']
const valid = valta.webhooks.verify(req.body, sig, process.env.VALTA_WEBHOOK_SECRET)
if (!valid) return res.status(400).end()
const { type, data } = req.body
if (type === 'agent.frozen') {
// Send Slack alert, page on-call, etc.
}
res.status(200).send('OK')
})
Reliability
- 5 retries with exponential backoff: 1s, 5s, 30s, 2min, 10min
- HMAC-SHA256 signature on every request — verify before processing
- Idempotency key on every event — safe to deduplicate on your end