Receive Provider Events with Triggers

A Trigger subscription watches one end user’s connected account and sends new provider events to your project webhook as trigger.message events. When a user’s Google Sheet gets a new row, a new email reaches their Gmail, or a Stripe payment changes state, your backend receives an event.

Connector runs the subscription: it polls providers and registers and receives provider webhooks. Your backend creates subscriptions and handles the events.

How events arrive

Push Triggers involve two URLs: your project webhook receives events from Connector, and the third-party callback URL (push.callbackUrl) receives events from the provider. Connector registers most callback URLs automatically; Slack, Microsoft Teams, Feishu, and Intercom need an administrator to enter it in the provider app.

Before you start

1. Complete the Connector for SaaS guide so that your backend has a Project API key and saves each user’s connectedAccountId.
2. Create a project webhook whose eventTypes include trigger.message and whose authTypes include the auth type of the accounts you subscribe to. Google accounts use oauth2. One webhook can receive events from every subscription in the project.
3. Have the end user connect the account that the Trigger reads.

If the account is routed to a dedicated webhook, events go only to that webhook, so it must meet these conditions instead.

Connector checks the webhook when you create or resume a subscription. Without an active webhook that matches, the request fails with trigger_delivery_unavailable.

Step 1: Choose a Trigger

List the published Triggers and read the config schema of the one you need:

curl --silent --show-error \
  'https://connector.oomol.com/v1/saas/trigger-types/googlesheets.on_row_added' \
  -H "Authorization: Bearer $PROJECT_API_KEY"

GET /v1/saas/trigger-types lists every published Trigger; add ?service=googlesheets to filter by provider. The catalog is the same for every project.

Step 2: Create a subscription

This example watches the Orders sheet for new rows:

curl --silent --show-error \
  'https://connector.oomol.com/v1/saas/trigger-subscriptions' \
  -H "Authorization: Bearer $PROJECT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: orders-sheet-customer-1' \
  --data @- <<JSON
{
  "userId": "customer-1",
  "connectedAccountId": "$CONNECTED_ACCOUNT_ID",
  "triggerId": "googlesheets.on_row_added",
  "config": {
    "spreadsheetId": "<spreadsheet-id>",
    "sheet": "Orders"
  },
  "intervalSeconds": 300
}
JSON

Send an Idempotency-Key header so that a retried request does not create a second subscription. The first request returns 201; replaying the same request with the same key returns 200 and the original subscription; reusing the key for a different request returns 409.

Save the returned id beside the user and account in your database. You can also create and manage subscriptions in Console: open the project and select Event subscriptions.

Receive events

Each event arrives at your project webhook as a signed trigger.message delivery. Verify the signature first, then read the envelope:

{
  "id": "evt_0199d2a8-4c1b-7e2f-8a3d-6b5c4d3e2f10",
  "type": "trigger.message",
  "version": 1,
  "createdAt": 1800000300000,
  "data": {
    "subscriptionId": "0199d290-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "triggerId": "googlesheets.on_row_added",
    "definitionVersion": 2,
    "externalUserId": "customer-1",
    "connectedAccountId": "0199d1f4-2e5f-7b61-8c72-9d0e1f2a3b4c",
    "providerConfigId": "0199d1a0-5f6e-7d8c-9b0a-1c2d3e4f5a6b",
    "service": "googlesheets",
    "payload": {
      "spreadsheetId": "<spreadsheet-id>",
      "sheetId": 0,
      "sheetTitle": "Orders",
      "rowNumber": 12,
      "row": { "Order ID": "A-1001", "Amount": 42 },
      "values": ["A-1001", 42]
    }
  }
}

data.payload follows the Trigger’s eventSchema. Use subscriptionId or externalUserId to route the event to the right user, and deduplicate by envelope id, which stays the same across retries and webhooks.

The first polling read only records the current position; existing rows, emails, or records are not sent. The subscription’s initialized field turns true after that read. Events created after it are sent on later reads.

Delivery uses the project webhook retry schedule. The same event can arrive more than once, and a delivery that runs out of retries or gets a non-retryable 4xx ends as failed; find those in Deliveries in Console or through the delivery records API. Each webhook has up to 5 requests in flight; a slow endpoint delays its own queue but not other webhooks. Events that reach a final state are kept for 7 days.

Manage subscriptions

A subscription shows status, pauseReason, initialized, nextPollAt, lastSuccessAt, lastError, and consecutiveFailures. Push subscriptions also show push.callbackUrl, push.setup (automatic or application), and push.ready. Deleting a subscription stops new reads; events recorded before deletion are still delivered.

When a subscription pauses

Connector pauses a subscription when it cannot continue safely. pauseReason tells you what to do:

Temporary provider errors do not pause a subscription. Connector retries with backoff from 30 seconds up to 30 minutes and records the latest error in lastError and consecutiveFailures.

If the user reconnects the same provider account, the subscription keeps working. If the user replaces it with a different provider account under the same alias, related subscriptions pause with checkpoint_reset_required.

Billing and team balance

Each event is billed once, when it is first delivered successfully to any webhook in the project. Reads, empty reads, retries, extra webhooks, and events that finally fail are not billed.

Triggers require a team balance that covers Connector usage:

• When the balance is below zero, creating or resuming a subscription returns 402 insufficient_credit. Reads and deliveries stop. Viewing, changing the interval, pausing, and deleting still work.
• When the balance cannot be verified, the same requests return 503 balance_unavailable with Retry-After: 30.
• While delivery is blocked, push events are buffered up to 10,000 pending items per project. Connector still acknowledges events beyond that limit to the provider but does not store them, so the provider does not resend them. After 7 days of confirmed insufficient credit, pending events expire and new push events are dropped the same way until the balance recovers. The billing view counts both cases.
• After the team adds credit, reads and deliveries resume automatically. Subscriptions paused for other reasons stay paused.

Subscription responses include a project billing summary with state (allowed, insufficient_credit, balance_unavailable, or unverified), the buffer size, and counts of rejected or expired events. List responses return it in meta.billing. unverified means the team balance has not been checked yet, usually because the project has no subscriptions; it does not block requests, and creating a subscription checks the balance.

Errors

Available Triggers

The catalog from GET /v1/saas/trigger-types is the source of truth.

Provider notes

Polling sends the state visible at each read; edits between two reads are not sent one by one. Subscriptions on the same provider account, base, or workspace share that provider’s rate limits.

Troubleshooting