Overview
The JoAi Trigger node is designed to automatically receive webhook events from JoAi agents. It simplifies integration by managing webhook lifecycle (creation, verification, deletion) transparently based on the workflow's activation state and environment changes.
This node is beneficial when you want to automate workflows triggered by specific events occurring in JoAi agents, such as actions performed by the agent, messages sent by the agent, or messages sent by users interacting with the agent.
Practical examples:
- Automatically process and log every message an agent sends.
- Trigger a workflow when a user sends a message to an agent, enabling real-time responses or analytics.
- React to specific agent actions (e.g., status changes) to update external systems or notify teams.
Properties
| Name | Meaning |
|---|---|
| Agent ID | The unique identifier (UUID) of the JoAi agent from which to receive webhook events. |
| Trigger On | The type of event to listen for from the JoAi agent. Options: |
| - Agent Action: Triggered when an agent performs an action | |
| - Agent Message: Triggered when an agent sends a message | |
| - User Message: Triggered when a user sends a message | |
| 🎉 Automatic Webhook Management | Informational notice explaining that webhooks are managed automatically by the node, including creation, deletion, and updates on environment changes. No manual setup required beyond providing Agent ID and trigger type. |
Output
The node outputs JSON data representing the webhook payload received from JoAi. The structure of this JSON depends on the event type but generally contains details about the agent event or message.
If the webhook secret token validation fails, the node responds with HTTP 403 and a JSON error message indicating "Invalid webhook secret".
No binary data output is produced by this node.
Dependencies
- Requires an API key credential for authenticating requests to the JoAi API.
- The node automatically manages webhooks via the JoAi API, so network access to JoAi services is necessary.
- No additional manual webhook configuration is needed; the node handles webhook registration and cleanup internally.
Troubleshooting
Common issues:
- Invalid or missing Agent ID will prevent webhook creation and event reception.
- Incorrect trigger type selection may cause the workflow not to activate on expected events.
- Network connectivity problems can cause webhook creation or deletion failures.
- If the webhook secret token does not match, incoming webhook calls will be rejected with a 403 error.
Error messages:
"Invalid webhook secret": Indicates the incoming webhook request did not include the expected secret token header or it mismatched. Ensure the workflow URL has not changed unexpectedly and the node is active.- Webhook creation or deletion errors logged internally usually relate to API authentication or network issues. Verify the API key credential and network access.
Resolution tips:
- Double-check the Agent ID and trigger type parameters.
- Ensure the workflow is activated to create the webhook.
- Confirm that the API key credential is valid and has sufficient permissions.
- Review logs for detailed error messages related to webhook management.
Links and References
- JoAi Official Documentation (replace with actual URL)
- n8n Webhook Node Concepts: https://docs.n8n.io/nodes/n8n-nodes-base.webhook/
- General webhook best practices: https://developer.mozilla.org/en-US/docs/Webhooks
Note: The node automatically handles webhook lifecycle, so no manual webhook setup is required beyond configuring the node properties.