Skip to main contentWebhooks are used for asynchronous workflows where the agent must wait for a callback from an external system before continuing.
How it Works
- Trigger: The agent runs a Webhook Creation capability.
- Register: Maitai creates a unique, per-session
webhook_url on the Maitai hooks service (e.g., https://hooks.trymaitai.ai/agent/<key>).
- Wait: The agent returns WAITING_WEBHOOK and pauses.
- Callback: Your external system POSTs an event payload to the
webhook_url.
- Resume: Maitai routes the payload to the correct agent + session and resumes execution.
Notes
- The
webhook_url is a Maitai-hosted callback endpoint. The webhook key is used to look up which agent/session is waiting.
- Maitai does not verify provider-specific signatures (e.g., Stripe’s
Stripe-Signature) at webhook ingress. Verify signatures in your own webhook handler before forwarding to Maitai if needed.
Use Cases
- Payment Processing: Waiting for a transaction to clear.
- Human-in-the-Loop: Waiting for a human agent to approve a specific action.
- Long-running Jobs: Waiting for a video to finish rendering or a report to be generated.
