Provider Subscriptions

Relevant source files

• apps/sim/blocks/blocks/grain.ts
• apps/sim/blocks/blocks/webflow.ts
• apps/sim/lib/webhooks/provider-subscriptions.ts
• apps/sim/lib/webhooks/provider-utils.ts
• apps/sim/triggers/airtable/webhook.ts
• apps/sim/triggers/ashby/application_submit.ts
• apps/sim/triggers/ashby/candidate_delete.ts
• apps/sim/triggers/ashby/candidate_hire.ts
• apps/sim/triggers/ashby/candidate_stage_change.ts
• apps/sim/triggers/ashby/job_create.ts
• apps/sim/triggers/ashby/offer_create.ts
• apps/sim/triggers/ashby/utils.ts
• apps/sim/triggers/calendly/invitee_canceled.ts
• apps/sim/triggers/calendly/invitee_created.ts
• apps/sim/triggers/calendly/routing_form_submitted.ts
• apps/sim/triggers/calendly/webhook.ts
• apps/sim/triggers/github/webhook.ts
• apps/sim/triggers/gmail/poller.ts
• apps/sim/triggers/googleforms/webhook.ts
• apps/sim/triggers/grain/highlight_created.ts
• apps/sim/triggers/grain/highlight_updated.ts
• apps/sim/triggers/grain/index.ts
• apps/sim/triggers/grain/item_added.ts
• apps/sim/triggers/grain/item_updated.ts
• apps/sim/triggers/grain/recording_created.ts
• apps/sim/triggers/grain/recording_updated.ts
• apps/sim/triggers/grain/story_created.ts
• apps/sim/triggers/grain/utils.ts
• apps/sim/triggers/grain/webhook.ts
• apps/sim/triggers/microsoftteams/chat_webhook.ts
• apps/sim/triggers/microsoftteams/webhook.ts
• apps/sim/triggers/outlook/poller.ts
• apps/sim/triggers/registry.ts
• apps/sim/triggers/stripe/webhook.ts
• apps/sim/triggers/telegram/webhook.ts
• apps/sim/triggers/typeform/webhook.ts
• apps/sim/triggers/webflow/collection_item_changed.ts
• apps/sim/triggers/webflow/collection_item_created.ts
• apps/sim/triggers/webflow/collection_item_deleted.ts
• apps/sim/triggers/webflow/form_submission.ts

This page documents the provider subscription system for webhooks that require active registration with external services. Provider subscriptions enable bidirectional webhook communication where Sim Studio must register callback URLs with third-party APIs (Teams, Telegram, Airtable, etc.) rather than passively receiving webhook calls.

For general webhook processing and authentication, see Webhook Processing Pipeline and Webhook Authentication. For webhook deduplication, see Webhook Deduplication.

---

Overview

Provider subscriptions manage the lifecycle of webhook registrations with external services that require explicit subscription creation. Unlike passive webhook providers (GitHub, Stripe) where users manually configure webhooks in the provider's UI, subscription-based providers require Sim Studio to programmatically:

1. Register webhook URLs with the provider's API when a workflow is deployed.
2. Maintain subscription state including external subscription IDs and expiration times.
3. Delete subscriptions when webhooks are removed or workflows are undeployed.
4. Refresh subscriptions for providers with time-limited subscriptions (e.g., Microsoft Teams).

The subscription system currently handles eleven providers: Microsoft Teams, Telegram, Airtable, Typeform, Calendly, Ashby, Grain, Fathom, Lemlist, Webflow, and Attio apps/sim/lib/webhooks/provider-subscriptions.ts14-25

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts1-25

---

Subscription Lifecycle

Creation Flow

Diagram: Mapping subscription creation logic to code entities

Subscriptions are created during workflow deployment or when a webhook is saved. The system:

1. Identifies the provider type in createExternalWebhookSubscription apps/sim/lib/webhooks/provider-subscriptions.ts1768-1810
2. Resolves the OAuth account and refreshes the access token using getCredentialOwner and refreshAccessTokenIfNeeded apps/sim/lib/webhooks/provider-subscriptions.ts35-60 apps/sim/lib/webhooks/provider-subscriptions.ts98-100
3. Checks for an existing externalSubscriptionId in the webhook.providerConfig to avoid duplicate registrations apps/sim/lib/webhooks/provider-subscriptions.ts110-126
4. Calls the provider-specific creation function (e.g., createTeamsSubscription, createAirtableWebhook) to register the notificationUrl apps/sim/lib/webhooks/provider-subscriptions.ts31-33

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts31-110 apps/sim/lib/webhooks/provider-subscriptions.ts1768-1810

---

Deletion Flow

Diagram: Mapping subscription deletion logic to code entities

Subscription deletion follows a best-effort strategy in cleanupExternalWebhook apps/sim/lib/webhooks/provider-subscriptions.ts1812-1850 Webhook deletion in the local database always succeeds even if the external API call fails.

The deletion process:

1. Retrieves the externalSubscriptionId from providerConfig apps/sim/lib/webhooks/provider-subscriptions.ts27-29
2. Attempts to refresh credentials to authorize the deletion request apps/sim/lib/webhooks/provider-subscriptions.ts221-235
3. Calls the provider's deletion API (e.g., DELETE /subscriptions/{id} for Teams) apps/sim/lib/webhooks/provider-subscriptions.ts241-260
4. Logs errors but never throws exceptions that would block the removal of the webhook record from the database apps/sim/lib/webhooks/provider-subscriptions.ts262-271

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts211-272 apps/sim/lib/webhooks/provider-subscriptions.ts1812-1850

---

Provider Implementations

Microsoft Teams (Graph API)

Teams uses Graph API subscriptions to monitor chat messages. These subscriptions are time-limited.

Property	Value
API Endpoint	https://graph.microsoft.com/v1.0/subscriptions apps/sim/lib/webhooks/provider-subscriptions.ts146
Max Lifetime	4230 minutes (~3 days) apps/sim/lib/webhooks/provider-subscriptions.ts132
Trigger ID	microsoftteams_chat_subscription apps/sim/lib/webhooks/provider-subscriptions.ts74

The implementation in createTeamsSubscription sets the resource to /chats/{chatId}/messages and includes a clientState set to the internal webhook.id for verification apps/sim/lib/webhooks/provider-subscriptions.ts128-143

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts66-184

Telegram (Bot API)

Telegram webhooks use the setWebhook method. Unlike other providers, Telegram only allows one webhook per bot token at a time.

Property	Value
API Endpoint	https://api.telegram.org/bot{token}/setWebhook apps/sim/lib/webhooks/provider-subscriptions.ts316
Authentication	Bot token in URL path
Method	POST

The createTelegramWebhook function extracts the botToken from the config and registers the notificationUrl apps/sim/lib/webhooks/provider-subscriptions.ts278-345

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts278-345

Airtable

Airtable webhooks monitor changes to specific bases and return a macSecret used for HMAC signature verification.

Property	Value
API Endpoint	https://api.airtable.com/v0/bases/{baseId}/webhooks apps/sim/lib/webhooks/provider-subscriptions.ts466
Required Config	baseId, credentialId apps/sim/lib/webhooks/provider-subscriptions.ts402-404
Stored Fields	externalId, expiresAt, macSecret apps/sim/lib/webhooks/provider-subscriptions.ts497-508

The createAirtableWebhook function validates the baseId format before calling the API and stores the returned macSecretBase64 for future request validation apps/sim/lib/webhooks/provider-subscriptions.ts392-511

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts392-511

Grain (v2 Webhooks)

Grain subscriptions are view-scoped. Each view ID corresponds to a specific content type (recordings, highlights, or stories) apps/sim/triggers/grain/webhook.ts34

Property	Value
API Endpoint	/_/public-api/webhooks apps/sim/triggers/grain/utils.ts51
Required Config	apiKey, viewId apps/sim/triggers/grain/webhook.ts15-35
Trigger Options	grain_item_added, grain_item_updated, grain_webhook apps/sim/triggers/grain/utils.ts8-11

The Grain implementation automatically creates the webhook when the trigger is saved and deletes it when removed apps/sim/triggers/grain/utils.ts52

Sources: apps/sim/triggers/grain/webhook.ts5-66 apps/sim/triggers/grain/utils.ts42-61

---

Polling Triggers (Alternative to Subscriptions)

For services like Gmail and Outlook that do not support standard webhook subscriptions for all event types or require complex Pub/Sub setups, Sim Studio uses a Polling architecture.

Gmail & Outlook Polling

These triggers use a polling: true flag in their configuration apps/sim/triggers/gmail/poller.ts33 apps/sim/triggers/outlook/poller.ts27

• Gmail: Monitors specific labels (Inbox, Sent, etc.) or uses a custom searchQuery apps/sim/triggers/gmail/poller.ts48-104
• Outlook: Monitors specific folders and can automatically mark emails as read apps/sim/triggers/outlook/poller.ts42-104

Sources: apps/sim/triggers/gmail/poller.ts26-154 apps/sim/triggers/outlook/poller.ts20-113

---

Subscription Challenges & Verification

Some providers perform reachability tests or challenges during the subscription process or upon receiving events.

1. Microsoft Graph: Sends a validationToken query parameter during registration that must be returned as a plain text response.
2. WhatsApp: Uses hub.mode, hub.verify_token, and hub.challenge parameters for endpoint verification.
3. Slack: Sends a url_verification event with a challenge field that must be echoed back in the response.
4. Pre-lookup Verification: For providers that probe the endpoint before a webhook record exists in the database, the system uses a pending-verification store to return successful responses.

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts1-1766

---

Provider Comparison Table

Provider	Auth Method	ID Storage Field	Signature Type
Teams	OAuth 2.0	externalSubscriptionId	clientState
Telegram	Bot Token	N/A	None
Airtable	OAuth / API Key	externalId	HMAC-SHA256
Typeform	OAuth 2.0	Tag (Webhook ID)	HMAC-SHA256
Calendly	OAuth 2.0	uri	HMAC-SHA256
Ashby	API Key	id	HMAC-SHA256
Attio	OAuth 2.0	webhook_id	HMAC-SHA256
Grain	API Key	externalId	None

Sources: apps/sim/lib/webhooks/provider-subscriptions.ts1-1766 apps/sim/triggers/grain/webhook.ts1-76