Garudust’s core exposes a single basic primitive: agent.run(task). Every entry point — whether it’s a chat message, a cron job, or a webhook call — ends up in the same call. This means that any external system that can send an HTTP POST can be an event trigger for Garudust. This article explains how it currently works, the patterns that work in production, and concrete use cases. How the Webhook Adapter Works When Garudust is set up to use the webhook platform, it launches the Axum HTTP server and registers a POST endpoint at the path you specified. Incoming requests will look like this: { “text”: “A new billing invoice has arrived from Acme Corp for $4,200.”, “callback_url”: “https://your-system.example.com/garudust/reply”, “user_id”: “billing-watcher”, “session_key”: “billing-acme-corp” } Enter fullscreen mode Exit fullscreen mode Field Required Description text ✅ Task prompt that the agent will use to run callback_url ✅ URL where Garudust will POST the response user_id optional Used for role-based access control session_key optional pin conversation history; If not specified, it defaults to webhook:{callback_url} Garudust wraps this information as InboundMessage, sent via GatewayHandler, spawns agent.run() and when the agent finishes working it will POST the response back to callback_url: { “text”: “Invoice from Acme Corp for $4,200 — categorised as SaaS/Infrastructure. Flagged for approval above $3,000 threshold. Draft approval request sent to #finance.” } Enter fullscreen mode Exit fullscreen mode The immediate HTTP response to your POST is 202 Accepted — agent works asynchronously Security Garudust checks the HMAC-SHA256 signature for every incoming request. shared secret in config and sign every outgoing POST with: ───────────────── ────────────────────────── Event source (email, → Webhook adapter calendar, DB, queue) Filter / match logic → Your code (before POST) Task description → agent.run(task) Result handling → handler at your callback_url Enter fullscreen mode Exit fullscreen mode Your system owns the filter — Garudust owns the running agent. Both sides do not need to know each other’s internal structure. Use Cases 1. Billing Email Monitor An email processing service that captures emails from billing senders. When it finds a matching email, it retrieves the subject, sender, and amount and triggers Garudust: { “text”: “New invoice received: Stripe — $1,840 for May 2026. Attach to this month’s expense report and notify the finance channel if it exceeds the $1,500 alert threshold.”, “callback_url”: “https://your-ops.example.com/hooks/garudust”, “session_key”: “finance-inbox” } Enter fullscreen mode Exit fullscreen mode Agent uses its tool to read expense report files, add line items, and post to Slack. The email service just matches the sender and shoots — no need to know anything about expense reports or Slack. 2. GitHub PR Review Gate GitHub Actions workflow Call Garudust after a PR opens in the main branch. The workflow creates the payload from GitHub context: { “text”: “PR #214 opened by @alice: ‘feat: add OAuth2 PKCE flow’. Changed files: src/auth/oauth.rs, src/auth/pkce.rs, tests/auth_integration.rs. Diff summary attached. Review for security issues in the auth flow and post a summary comment.”, “callback_url”: “https://your-ci.example.com/garudust/pr-review”, “session_key”: “pr-214” } Enter fullscreen mode Exit fullscreen mode GitHub webhook Launch workflow → workflow Create task text → Garudust review and session_key tied to the PR number cause the next trigger (new commit, repeat review request) to continue in the same conversation thread. 3. Database Anomaly Alert Monitoring job query the database according to the schedule table and check the aggregate metric when the metric crosses the threshold. Instead of sending a static alert, it fires Garudust instead: { “text”: “Anomaly detected: orders table insert rate dropped 94% in the last 10 minutes (baseline 340/min, current 19/min). Last successful insert: 09:42 UTC. Investigate root cause and summarise for on-call.”, “callback_url”: “https://ops.example.com/garudust/incidents”, “session_key”: “incident-2026-05-23-orders” } Enter fullscreen mode Exit fullscreen mode Agent can use terminal or database tool to run additional queries, check deploy Latest and structured incident summary — monitoring job only checks for threshold breaches 4. Calendar External-Attendee Watch Integration layer poll Google Calendar (or receive push notification) and fire Garudust when an event is created with an attendee whose domain doesn’t match your organization: { “text”: “New calendar event: ‘Q3 partnership discussion’ on 2026-06-04 14:00 UTC. External attendees: jane@partner.com, bob@partner.com. Prepare a one-page briefing on Partner Corp using the CRM notes and recent email thread.”, “callback_url”: “https://your-system.example.com/garudust/calendar”, “session_key”: “meeting-prep-2026-06-04” } Enter fullscreen mode Exit fullscreen mode Calendar integration own filter logic “external attendee” – Garudust Take ownership of the briefing 5. Queue Worker Trigger Background worker pulls jobs from the task queue (SQS, Redis, RabbitMQ) and sends each piece to Garudust for work. Suitable for workloads that vary and require the agent to handle each piece in its own way: { “text”: “Customer support ticket #8821 (priority: high): User reports that export to CSV silently truncates rows above 10,000. Reproduce the scenario, identify the code path responsible, and draft a fix description for the engineering team.”, “callback_url”: “https://support.example.com/garudust/tickets”, “session_key”: “ticket-8821” } Enter fullscreen mode Exit fullscreen mode Queue worker dequeue, format task text, fire webhook Multiple tickets can be run as concurrent agent sessions simultaneously Session Keys and session_key are what make event triggers useful beyond traditional tasks. one-shot When you pin a key, all webhook calls that use the same key share a conversation history. This means: PR review trigger on commit 1 and re-review trigger on commit 2 are the same conversation — the agent remembers what was said earlier. Incident trigger and “How are you?” that the on-call engineer asks later use the same context. Billing session Accumulate invoices for a whole month from multiple triggers before creating a monthly summary. If you want completely separate sessions (each event is independent), you don’t need to specify a session_key — Garudust It uses callback_url as the key instead, giving a new context to the callback target that is unique. What this pattern doesn’t cover with the Webhook adapter is push targets — the external system must initiate the connection. If you want Garudust to pull data from the source itself (check inbox, poll API, watch files) without needing a scheduler, you have to use a cron job that polls or wait for a primitive watch/filter that doesn’t currently exist. For use cases that are truly push-based (GitHub webhook, queue worker, calendar push notification, email routing service), the current architecture supports it all and the division of duties is already clear.
Source link
