This document describes the webhook authentication system in Sim, which verifies incoming webhook requests from external providers to prevent unauthorized execution of workflows. For information about webhook processing and execution flow, see Webhook Processing Pipeline. For details on provider-specific subscription management, see Provider Subscriptions.
The webhook authentication system validates incoming HTTP requests to webhook endpoints before they trigger workflow executions. Each provider implements specific authentication mechanisms (HMAC signatures, bearer tokens, custom headers) to ensure requests originate from legitimate sources. The system supports environment variable resolution for secrets, allowing dynamic configuration across workspaces.
Key responsibilities:
The POST /api/webhooks/trigger/[path] route serves as the entry point for all incoming webhooks. It performs body parsing, challenge handling, and multi-webhook lookup (for credential set fan-out) before delegating to the authentication logic.
Sources: apps/sim/app/api/webhooks/route.ts:177-200, apps/sim/lib/webhooks/utils.server.ts:30-91
| Provider | Authentication Method | Header/Config | Validation Function |
|---|---|---|---|
| GitHub | HMAC-SHA256 (preferred) HMAC-SHA1 (legacy) | X-Hub-Signature-256X-Hub-Signature | validateGitHubSignature() |
| Linear | HMAC-SHA256 | Linear-Signature | validateLinearSignature() |
| Attio | HMAC-SHA256 | Attio-Signature | validateAttioSignature() |
| Circleback | HMAC-SHA256 | x-signature | validateCirclebackSignature() |
| Cal.com | HMAC-SHA256 | X-Cal-Signature-256 | validateCalcomSignature() |
| Jira | HMAC-SHA1 | X-Hub-Signature | validateJiraSignature() |
| Confluence | HMAC-SHA1 | X-Hub-Signature | validateJiraSignature() |
| Typeform | HMAC-SHA256 | Typeform-Signature | validateTypeformSignature() |
| Fireflies | HMAC-SHA1 | x-hub-signature | validateFirefliesSignature() |
| Twilio Voice | HMAC-SHA1 | x-twilio-signature | validateTwilioSignature() |
| Microsoft Teams | HMAC-SHA256 | Authorization: HMAC <sig> | validateMicrosoftTeamsSignature() |
| Google Forms | Bearer Token or Custom Header | Configurable | String comparison |
| Generic | Bearer Token or Custom Header | Configurable | String comparison |
Sources: apps/sim/lib/webhooks/utils.server.ts:30-102
The system handles branching logic for all supported providers. It is called within the route handler loop for every webhook matching the incoming path.
The authentication flow follows this pattern:
{{VARIABLE}} placeholders in providerConfig using resolveProviderConfigEnvVars().safeCompare() apps/sim/lib/webhooks/utils.server.ts8null for success, or a NextResponse with a 401/403 status for failure.Sources: apps/sim/lib/webhooks/utils.server.ts:8-102, apps/sim/app/api/webhooks/route.ts:188-210
Webhook secrets often reference environment variables using the syntax {{VARIABLE_NAME}}. This allows dynamic configuration across workspaces and prevents hardcoding sensitive secrets in workflow definitions.
Implementation Details:
resolveEnvVarsInObject iterates through the providerConfig object and applies resolution to all string values apps/sim/app/api/webhooks/route.ts12mergeNonUserFields ensures that system-managed fields are preserved while respecting user-provided resolved values apps/sim/lib/webhooks/utils.ts26-36Sources: apps/sim/app/api/webhooks/route.ts:12-18, apps/sim/lib/webhooks/utils.ts:26-36
Many providers (Slack, WhatsApp, Microsoft Graph) send "probes" or "challenges" to verify the endpoint before sending real data.
The verification logic processes these probes early in the request lifecycle.
Key Verification Logic:
token against the verificationToken stored in the providerConfig for that specific webhook path. If valid, it returns the challenge string apps/sim/lib/webhooks/utils.server.ts30-91url_verification events by echoing the challenge field in a JSON response apps/sim/lib/webhooks/utils.server.ts96-102Sources: apps/sim/lib/webhooks/utils.server.ts:30-102
All sensitive comparisons (signatures, tokens) use safeCompare apps/sim/lib/webhooks/utils.server.ts8 This utility ensures that the comparison time does not depend on the value of the inputs, mitigating timing attacks.
When webhooks involve fetching external assets (e.g., Teams message attachments), the system uses secureFetchWithPinnedIP and validateUrlWithDNS to prevent SSRF and DNS rebinding attacks apps/sim/lib/webhooks/utils.server.ts111-143
For polling-based triggers like IMAP, the system validates the database host and uses DNS pinning before establishing a connection to prevent malicious redirects apps/sim/lib/webhooks/imap-polling-service.ts175-184
Sources: apps/sim/lib/webhooks/utils.server.ts:8-143, apps/sim/lib/webhooks/imap-polling-service.ts:175-184
| Entity | File Path | Role |
|---|---|---|
handleWhatsAppVerification | apps/sim/lib/webhooks/utils.server.ts30 | Logic for Meta/WhatsApp verification |
handleSlackChallenge | apps/sim/lib/webhooks/utils.server.ts96 | Responds to Slack URL verification probes |
fetchWithDNSPinning | apps/sim/lib/webhooks/utils.server.ts111 | Securely fetches external content with DNS protection |
mergeNonUserFields | apps/sim/lib/webhooks/utils.ts26 | Preserves system fields during config resolution |
pollImapWebhooks | apps/sim/lib/webhooks/imap-polling-service.ts119 | Main loop for polling-based email triggers |
imapPollingTrigger | apps/sim/triggers/imap/poller.ts8 | UI configuration for IMAP trigger authentication |
Sources: apps/sim/lib/webhooks/utils.server.ts:30-143, apps/sim/lib/webhooks/utils.ts:26-36, apps/sim/lib/webhooks/imap-polling-service.ts:119-222, apps/sim/triggers/imap/poller.ts:8-66
Refresh this wiki