Trigger your AI employees from anywhere.
Every Oya AI employee gets a unique webhook URL. POST a JSON payload, and your employee runs — for as long as it needs to — with the input you sent. HMAC-signed so you can verify the request, async-safe so long-running tasks don’t time out, structured so you can wire any platform into it.
What it does
Universal trigger
Anything that can fire a webhook can trigger an AI employee — Stripe events, Typeform submissions, your own backend, GitHub Actions, Zapier, n8n, or a curl command. JSON in, run out.
HMAC-signed for verification
Each webhook is signed with a secret you control. Your employee verifies the signature before running, so a leaked URL alone isn’t enough to invoke an agent.
Async-safe with polling
POST returns a job id immediately. Long-running tasks (multi-step research, batch processing, report generation) run asynchronously while your caller polls for the result.
How to set up a Webhook trigger
- 1
Open your AI employee’s Triggers page
Click Triggers, then "Add Webhook trigger". You get a unique URL plus a signing secret.
- 2
Copy the URL and the secret
Paste the URL into whatever service is going to trigger this employee. Stash the secret somewhere safe — you’ll use it to sign requests.
- 3
POST a JSON payload to fire a run
Send a POST with `Content-Type: application/json` and a JSON body. The signing header (X-Oya-Signature) carries the HMAC-SHA256 of the body, computed with your secret. Full example in the Triggers docs.
- 4
Poll for the result (or fire-and-forget)
The response contains a job id. Hit GET /api/runs/{job_id} to check status. For tasks where you don’t care about the result (e.g. notifying your agent of a new sale), just let it run.
Detailed walkthrough with screenshots: Channels & Apps in the docs.
What it doesn’t do (yet)
We’d rather be upfront about the edges than promise things we don’t deliver.
- Webhook payloads are JSON-only today — multipart/form-data is on the roadmap.
- Maximum body size is 1 MB. For larger payloads, send a URL the agent can fetch (and authorize the agent for whatever store you used).
- Replay attacks are prevented by HMAC + a timestamp window. If your sender can’t add a timestamp, contact us and we’ll relax that for your tenant.
Frequently asked
How do I authenticate webhook requests?
Each webhook trigger has a unique signing secret. Compute HMAC-SHA256 over the request body with that secret and send it in the X-Oya-Signature header. Our verifier rejects unsigned or wrong-signature requests with 401.
What does the agent see when a webhook fires?
The full JSON body of the POST. Your agent’s system prompt should say what to do with it — e.g. "the body contains a Stripe customer.created event; greet the new customer in the welcome channel and add them to the CRM sheet."
How long can a webhook-triggered run last?
Long. Webhooks are async — POST returns immediately with a job id, the run continues until the agent finishes (could be seconds or minutes). For multi-step workflows that take a while, that’s the right model.
Can I trigger the same employee from multiple sources?
Yes. Create one webhook trigger per source so signatures and audit logs stay clean, or share one across sources if you’d rather differentiate inside the payload. Both work.
How do I rotate the signing secret?
Open the trigger settings, click Rotate. The old secret keeps working for a 24-hour grace window so callers can switch over, then it’s revoked.
Does Oya store the webhook payload?
It’s captured in the run’s audit log so you can see what triggered each run. After your account’s retention window it’s purged. Payloads are never used to train any AI model.
A note on AI accuracy
Oya’s AI employees are powered by large language models and may produce inaccurate, incomplete, or out-of-date responses. They are tools to assist your work, not authoritative sources. Always verify important information — especially numbers, dates, names, and any business or financial action — before relying on AI-generated output. If your AI employee suggests a destructive action (deleting data, sending money, posting publicly), confirm it yourself before approving.
No model training
Your data is not used to train AI models. It’s used to do the work you asked for, then logged in your run history for your audit.
Full audit trail
Every AI employee action maps to a run in Oya. Inputs, outputs, tools used, cost — all visible and auditable.
Wire any service into an AI employee.
Free trigger setup. $10 in free credits. Build something this afternoon.