> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymaitai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Handling asynchronous callbacks and long-running tasks

**Webhooks** are used for asynchronous workflows where the agent must wait for a callback from an external system before continuing.

### How it Works

1. **Trigger**: The agent runs a **Webhook Creation** capability.
2. **Register**: Maitai creates a unique, per-session `webhook_url` on the Maitai hooks service (e.g., `https://hooks.trymaitai.ai/agent/<key>`).
3. **Wait**: The agent returns **WAITING\_WEBHOOK** and pauses.
4. **Callback**: Your external system POSTs an event payload to the `webhook_url`.
5. **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.
* Webhook Creation actions are always **foreground**: they pause the session, so they can't run as background enrichment. They work in both [execution modes](/build/agents/execution_mode): the reasoning loop pauses mid-task, and a routed webhook action pauses until the callback arrives.

### 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.