The webhook system enables external services to trigger workflow executions in response to events. It handles incoming HTTP requests from 30+ providers, performs authentication and validation, and queues executions for asynchronous processing. This document covers the complete webhook processing pipeline from request receipt through background execution.
For information about workflow execution after webhooks are queued, see Workflow Execution Engine. For trigger configuration in the UI, see Workflow Triggers. For OAuth provider setup, see OAuth Provider System.
The webhook system processes incoming requests through a multi-stage pipeline that validates, authenticates, and queues webhook events for execution. The core logic is distributed between the dynamic route handler and the WebhookProcessor.
Title: Webhook Processing Flow
Sources: apps/sim/app/api/webhooks/trigger/[path]/route.ts:48-192, apps/sim/lib/webhooks/processor.ts73-118 apps/sim/background/webhook-execution.ts251-340
The webhook system manages lifecycle and event processing through several API routes.
/api/webhooks/trigger/[path])The primary entry point for external events. It handles both GET (for provider verification challenges like WhatsApp or Microsoft Graph) and POST for actual event delivery apps/sim/app/api/webhooks/trigger/[path]/route.ts:28-61.
Key responsibilities:
handleProviderChallenges apps/sim/app/api/webhooks/trigger/[path]/route.ts:36-39./api/webhooks)The management route handles CRUD operations. It supports collaborative access control via authorizeWorkflowByWorkspacePermission apps/sim/app/api/webhooks/route.ts95-101
createExternalWebhookSubscription apps/sim/app/api/webhooks/route.ts224-226Sources: apps/sim/app/api/webhooks/trigger/[path]/route.ts:28-192, apps/sim/app/api/webhooks/route.ts66-181
The system uses a registry pattern to decouple generic webhook logic from provider-specific implementation details. The getProviderHandler function returns an object implementing WebhookProviderHandler apps/sim/lib/webhooks/processor.ts20
Title: Webhook Provider Registry Mapping
The handler provides hooks for the entire lifecycle:
handleChallenge: For initial URL verification apps/sim/lib/webhooks/processor.ts132-133verifyAuth: For signature validation (HMAC, Bearer, etc.) apps/sim/app/api/webhooks/trigger/[path]/route.ts:114-120.shouldSkipEvent: For provider-side filtering (e.g., ignoring bot messages) apps/sim/lib/webhooks/processor.ts198-207Sources: apps/sim/lib/webhooks/processor.ts123-208 apps/sim/app/api/webhooks/trigger/[path]/route.ts:114-120, apps/sim/lib/webhooks/providers/registry.ts51-95
For services like Gmail and Outlook, the system uses a Polling strategy or a "Fan-out" approach for multiple accounts.
The syncWebhooksForCredentialSet function manages the lifecycle of webhooks when a "Credential Set" (a pool of multiple accounts) is used as a trigger.
isPollingWebhookProvider is true, it creates unique paths per credential (e.g., base-path-cred123) to allow independent polling apps/sim/lib/webhooks/utils.server.ts188-190Triggers like Gmail and Outlook are identified as polling providers via isPollingWebhookProvider apps/sim/triggers/constants.ts These are triggered by a system cron job rather than incoming HTTP requests apps/sim/app/api/schedules/execute/route.ts33-40
Sources: apps/sim/lib/webhooks/utils.server.ts47-212 apps/sim/app/api/schedules/execute/route.ts33-80
Once a webhook is queued, it is processed by executeWebhookJob in the background.
Webhooks often carry binary data (e.g., email attachments, Slack files). The WebhookAttachmentProcessor handles this by:
WebhookAttachment apps/sim/background/webhook-execution.ts105-117To prevent double-processing of the same event, the system uses IdempotencyService. It generates a hash of the request and stores it in the webhookIdempotency table apps/sim/background/webhook-execution.ts10
Sources: apps/sim/background/webhook-execution.ts10-17 apps/sim/background/webhook-execution.ts58-128 apps/sim/background/webhook-execution.ts152-211
Refresh this wiki