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 system also supports advanced features like IMAP/Email polling for providers that do not support push webhooks.
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.
Title: Webhook Processing Flow
Sources: apps/sim/app/api/webhooks/route.ts177-200 apps/sim/lib/webhooks/utils.server.ts30-91
The webhook system exposes two HTTP methods on the dynamic route /api/webhooks/trigger/[path].
The GET handler supports provider-specific verification challenges that occur during webhook registration. Providers like Microsoft Graph and WhatsApp send GET requests with query parameters to verify endpoint reachability.
Title: Webhook GET Verification Flow
The handleWhatsAppVerification function specifically checks for:
hub.mode, hub.verify_token, and hub.challenge parameters to confirm endpoint ownership apps/sim/lib/webhooks/utils.server.ts30-91Sources: apps/sim/lib/webhooks/utils.server.ts30-91 apps/sim/app/api/webhooks/route.ts62-174
The POST handler processes actual webhook events. It supports multiple webhooks sharing the same path (credential set fan-out) and processes each webhook sequentially.
| Step | Function | Purpose |
|---|---|---|
| 1 | handleSlackChallenge | Handle POST-based challenges (e.g., Slack url_verification) apps/sim/lib/webhooks/utils.server.ts96-102 |
| 2 | syncWebhooksForCredentialSet | Synchronizes webhooks across multiple credentials in a set apps/sim/app/api/webhooks/route.ts23-24 |
| 3 | formatTeamsGraphNotification | Formats raw Teams/Microsoft Graph notifications into standard payloads apps/sim/lib/webhooks/utils.server.ts148-212 |
| 4 | createExternalWebhookSubscription | Subscribes to third-party APIs (Teams, Telegram, etc.) apps/sim/app/api/webhooks/route.ts15-17 |
Sources: apps/sim/app/api/webhooks/route.ts177-230 apps/sim/lib/webhooks/utils.server.ts96-102
For services that do not support push webhooks (like standard IMAP email), the system uses a polling architecture managed by the ImapPollingService.
Title: IMAP Polling System
lastProcessedUidByMailbox to avoid duplicate processing apps/sim/lib/webhooks/imap-polling-service.ts29pollingIdempotency service to ensure each email message ID is processed only once apps/sim/lib/webhooks/imap-polling-service.ts9MAX_CONSECUTIVE_FAILURES to prevent infinite loops on bad credentials apps/sim/lib/webhooks/imap-polling-service.ts85-99Sources: apps/sim/lib/webhooks/imap-polling-service.ts1-120 apps/sim/triggers/imap/poller.ts8-15
Each provider implements its own webhook authentication mechanism. The system supports HMAC-SHA256, HMAC-SHA1, and custom header verification. For details, see Webhook Authentication.
fetchWithDNSPinning and validateUrlWithDNS functions prevent DNS rebinding attacks when fetching content (like email attachments) referred to in webhook payloads apps/sim/lib/webhooks/utils.server.ts111-143safeCompare for all credential and token checks to mitigate timing attacks apps/sim/lib/webhooks/utils.server.ts8Sources: apps/sim/lib/webhooks/utils.server.ts8-143
Webhooks are closely tied to the credentialSetId. When a webhook is created or updated, the system can "fan-out" the configuration across all credentials in a set using syncWebhooksForCredentialSet apps/sim/app/api/webhooks/route.ts23-24
For providers requiring explicit registration (e.g., Teams, Airtable), the createExternalWebhookSubscription and cleanupExternalWebhook functions manage the lifecycle during block creation or deletion apps/sim/app/api/webhooks/route.ts15-17 apps/sim/app/api/webhooks/[id]/route.ts:11-11.
Sources: apps/sim/app/api/webhooks/route.ts1-200 apps/sim/app/api/webhooks/[id]/route.ts:148-203
Refresh this wiki