docs/docs/en/integration/workflow-webhook/index.md
Through Webhook triggers, NocoBase can receive HTTP calls from third-party systems and automatically trigger workflows, enabling seamless integration with external systems.
Webhooks are a "reverse API" mechanism that allows external systems to proactively send data to NocoBase when specific events occur. Compared to active polling, Webhooks provide a more real-time and efficient integration approach.
External survey systems, registration forms, and customer feedback forms push data to NocoBase via Webhook after user submission, automatically creating records and triggering follow-up processes (such as sending confirmation emails, assigning tasks, etc.).
Events from third-party messaging platforms (such as WeCom, DingTalk, Slack) like new messages, mentions, or approval completions can trigger automated processes in NocoBase through Webhooks.
When data changes in external systems (such as CRM, ERP), Webhooks push updates to NocoBase in real-time to maintain data synchronization.
Locate and install the Workflow: Webhook plugin in the plugin manager.
Note: This is a commercial plugin. For detailed activation instructions, please refer to: Commercial Plugin Activation Guide
Add workflow nodes based on business requirements, such as:
After workflow creation, the system generates a unique Webhook URL, typically in the format:
https://your-nocobase-domain.com/api/webhooks/your-workflow-key
Configure the generated Webhook URL in the third-party system:
Test the Webhook using tools like Postman or cURL:
curl -X POST https://your-nocobase-domain.com/api/webhooks/your-workflow-key \
-H "Content-Type: application/json" \
-d '{"event":"test","data":{"message":"Hello NocoBase"}}'
In workflows, access Webhook data through variables:
{{$context.data}}: Request body data{{$context.headers}}: Request headers{{$context.query}}: URL query parameters{{$context.params}}: Path parametersReturns results after workflow execution completes, configurable:
Returns immediate confirmation, workflow executes in background. Suitable for:
Most third-party services support signature mechanisms:
// Example: Verify GitHub Webhook signature
const crypto = require('crypto');
const signature = context.headers['x-hub-signature-256'];
const payload = JSON.stringify(context.data);
const secret = 'your-webhook-secret';
const expectedSignature = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
if (signature !== expectedSignature) {
throw new Error('Invalid signature');
}
Ensure NocoBase is deployed with HTTPS to protect data transmission.
Configure IP whitelist to allow only trusted sources.
Add data validation logic in workflows to ensure correct format and valid content.
Record all Webhook requests for tracking and troubleshooting.
Some third-party services retry sending if they don't receive a successful response:
// 1. Verify data source
// 2. Parse form data
const formData = context.data;
// 3. Create customer record
// 4. Assign to relevant owner
// 5. Send confirmation email to submitter
if (formData.email) {
// Send email notification
}
// 1. Parse push data
const commits = context.data.commits;
const branch = context.data.ref.replace('refs/heads/', '');
// 2. If main branch
if (branch === 'main') {
// 3. Trigger deployment process
// 4. Notify team members
}