Webhooks

Webhooks are HTTP callbacks that notify your application when events happen. When an event occurs in AgentCanvas, we send an HTTP POST request to your configured webhook URL with event data.

Unlike polling (checking for updates repeatedly), webhooks deliver events instantly when they happen, reducing latency and server load.

AgentCanvas can receive webhooks from external services and trigger workflows:

• Generic webhooks: POST /webhooks/{webhook_id} - Receive any webhook format
• GitHub webhooks: POST /webhooks/{webhook_id}/github - Specialized endpoint with signature verification
• GitLab webhooks: POST /webhooks/{webhook_id}/gitlab - GitLab-specific endpoint
• Slack webhooks: POST /webhooks/{webhook_id}/slack - Slack slash commands and webhooks

Webhooks are processed asynchronously in the background. The system extracts event types from headers (x-github-event, x-gitlab-event, x-webhook-event) and triggers associated workflows.

Common webhook events you can receive:

• Workflow started: Notified when a workflow execution begins
• Workflow completed: Notified when a workflow finishes successfully
• Workflow failed: Notified when a workflow execution fails
• Node completed: Notified when a specific node finishes execution
• Error occurred: Notified when errors happen during execution
• Status changed: Notified when workflow status changes

You can configure which events trigger webhooks in your workflow settings or through the API.

Secure your webhooks to prevent unauthorized access:

• Webhook secrets: Configure a secret to verify webhook authenticity
• HTTPS only: Webhook URLs must use HTTPS (not HTTP)
• Signature verification: GitHub and GitLab webhooks include signature headers for verification
• IP whitelisting: Optionally restrict webhooks to specific source IPs

The system includes webhook source IP information in event data, and some providers (like GitHub) include signature headers that you can verify to ensure the webhook is authentic.

How webhooks are processed:

1. Receive webhook: The system receives an HTTP POST request at your webhook URL
2. Extract data: Parses JSON or form-encoded data, extracts headers and source IP
3. Determine event type: Identifies event type from headers (x-github-event, x-gitlab-event, etc.)
4. Queue for processing: Adds the webhook event to a background task queue
5. Trigger workflow: Processes the webhook asynchronously and triggers associated workflows
6. Return response: Immediately returns 202 Accepted to acknowledge receipt

Webhooks are processed asynchronously to ensure fast response times. The system automatically retries failed webhook deliveries.