Feat/webhook notifications

[GreatShinro]

feat: add webhook notifications after every agent task

Summary

PayFiAgent previously had no way to notify external systems of task outcomes. This PR adds a fire-and-forget webhook system that POSTs AgentResult as signed JSON to a configurable URL after every run() call — both success and failure.

Changes

backend/config.ts

Two new optional env vars added to EnvSchema and AgentConfig:

Variable	Type	Description
WEBHOOK_URL	string (URL)	Endpoint to POST task results to. No-op when absent.
WEBHOOK_SECRET	string	Signs the payload with HMAC-SHA256. No signature header when absent.

backend/webhook.ts (new)

• signPayload(payload, secret) — returns HMAC-SHA256 hex digest of the payload string
• dispatchWebhook(result) — no-ops if WEBHOOK_URL is unset; otherwise:
  • Serialises AgentResult to JSON
  • Attaches X-Nodal-Signature header when WEBHOOK_SECRET is set
  • POSTs via axios with up to 3 retries through the existing withRetry helper
  • Swallows all delivery errors — webhook failures never block or throw to the caller

backend/agent.ts

• dispatchWebhook(result) called (fire-and-forget via void) after both the success and failure return result paths in run()

tests/webhook.test.ts (new)

6 tests:

Test	Covers
HMAC-SHA256 produces correct hex digest	signPayload correctness
No-op when WEBHOOK_URL is unset	Guard condition
POSTs AgentResult as JSON to configured URL	Happy path
X-Nodal-Signature header matches expected HMAC	Signature correctness
POSTs on task failure result	Failure path
Does not throw when axios.post rejects	Error swallowing

Testing

npx vitest run tests/webhook.test.ts

✓ tests/webhook.test.ts (6 tests) 11ms
Test Files  1 passed (1)
      Tests  6 passed (6)

Security Notes

• WEBHOOK_SECRET never appears in logs — it is only used inside signPayload and is not attached to the config object's public surface beyond the optional field
• Delivery failures are swallowed with a log.warn — a broken webhook endpoint cannot crash or stall the agent
• Signature verification is the responsibility of the receiving server: compare X-Nodal-Signature against HMAC-SHA256(secret, rawBody)

closes #113

[drips-wave]

@GreatShinro Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits