Dexby

Triggers and webhooks

Get signed events on your server when something happens in a user's app or your project.

A webhook endpoint is a URL on your server. Dexby posts project events to it, signed with the Standard Webhooks scheme. A trigger listens for one event, such as a new Slack message, on one user's connection and forwards it to your webhooks.

Add a webhook endpoint

In the dashboard, open Configure → Webhooks, click Add endpoint, enter a public https URL, and pick events. Copy the signing secret (whsec_...). It is shown once.

Verify each delivery

webhook.ts
import { Webhook } from 'standardwebhooks'

const webhook = new Webhook(process.env.DEXBY_WEBHOOK_SECRET ?? '')

export async function POST(request: Request) {
	const body = await request.text()
	const event = webhook.verify(body, Object.fromEntries(request.headers)) // throws if forged
	console.log(event)
	return new Response(null, { status: 204 })
}

Answer 2xx within 10 seconds. Anything else is retried for about two days. webhook-id stays the same on every retry, so use it to drop duplicates.

To change the secret, choose Rotate signing secret in the endpoint's menu. Until the old secret stops, webhook-signature carries one signature for each secret, so a receiver holding either one verifies the delivery.

Create a trigger

Connect a WooCommerce account for the user before creating this order.created trigger.

trigger.ts
import { Dexby } from '@dexby.ai/sdk'

const dexby = new Dexby()

const trigger = await dexby.createTrigger({
	connectionId: '<connection-id>',
	event: 'order.created'
})
if (trigger.isErr()) throw new Error(trigger.error.message)
  • <connection-id>: the user's connected WooCommerce account, from Operate → Connections → open the account → Connection ID, or GET /v1/connections?userId=user_123.
  • event: an event the app supports (table below). Or create the trigger in Operate → Triggers → New trigger, which lists them.

Events then arrive as trigger.fired, with data.userId set to your user. Pass that id when creating the agent's session so it uses that user's connected accounts.

Apps with triggers

AppEventsSetup
Airtablerecord_created, record_updated, record_deleted (needs baseId and tableId)Automatic
Asanatask_added, task_changed, task_removed, task_deleted, comment_added (needs project)Automatic
Boxfile_uploaded, file_moved, file_renamed, file_trashed, file_restored, folder_created, comment_created (needs folderId)Automatic
Calendlyinvitee.created, invitee.canceled, invitee_no_show.created, invitee_no_show.deletedAutomatic
ClickUptask_created, task_updated, task_status_updated, task_assignee_updated, task_moved, task_deleted, task_comment_posted, list_created (needs workspaceId)Automatic
Dropboxfile_changed, folder_added, deletedOAuth app
Figmafile_updated, file_version_updated, file_commented, file_deleted, library_published, dev_mode_status_updated (needs context, contextId)Automatic
GitHubpush, pull_request_opened, pull_request_merged, pull_request_closed, issue_opened, issue_comment_created, release_published, workflow_run_completedGitHub App
GitLabpush, tag_push, issue, merge_request, note, pipeline, job, release (needs projectId)Automatic
Linearissue_created, issue_updated, issue_removed, comment_created, project_updatedOAuth app
Gmailemail_receivedOAuth app
Google Calendarevent_changed, event_cancelledAutomatic
Google Drivefile_changed, file_trashed, file_removedAutomatic
HubSpotcontact_created, contact_deleted, company_created, deal_created, deal_stage_changed, ticket_createdOAuth app
Intercomconversation_created, conversation_user_replied, conversation_admin_replied, conversation_assigned, conversation_closed, contact_user_created, ticket_createdOAuth app
Jiraissue_created, issue_updated, issue_deleted, comment_created, comment_updated, comment_deleted (needs project)Automatic
Microsoft Teamschat_message, channel_message (needs teamId and channelId)Automatic
monday.comcreate_item, change_column_value, change_status_column_value, change_name, create_update, item_archived, item_deleted, create_subitem (needs boardId)Automatic
OneDrivefile_changed, file_deletedAutomatic
Outlookemail_received, event_created, event_updated, event_deletedAutomatic
Notionpage_created, page_content_updated, page_properties_updated, page_deleted, comment_createdOAuth app
Salesforcelead_created, lead_updated, and the same for contact, account, opportunity and caseAutomatic
ShipStationtrack, fulfillment_shipped_v2, fulfillment_rejected_v2, batchAutomatic
Slackmessage, app_mention, reaction_addedManual
Telegrammessage, edited_message, channel_post, callback_queryAutomatic
Typeformform_response (needs formId)Automatic
Zoommeeting_created, meeting_updated, meeting_deleted, meeting_started, meeting_ended, participant_joined, participant_left, recording_completed, transcript_completedOAuth app
WooCommerceorder.created, order.updated, product.created, product.updated, customer.createdAutomatic

Manual (Slack): pass secret (your Slack app's Signing secret). The response has a url, shown once. Paste it as the Request URL under Event Subscriptions in your Slack app, and subscribe to the bot event.

GitHub App: GitHub sends events from every repository the GitHub App is installed on. If the user has not installed it anywhere, creating the trigger fails with APP_NOT_INSTALLED and an installUrl to install it. New installations are picked up automatically.

Notion: an event reaches only the accounts whose Notion connection can see its page. With your own Notion connection, create its webhook subscription with the auth config's Event URL. Notion sends a verification token there once: in the auth config, choose Show token, paste it into Notion's Verify box, then choose Save as webhook secret.

Google: Google only says that something changed, so Dexby reads what changed and sends one event per new email, changed calendar event or changed file. Dexby renews Google's watch before it expires. email_received carries the message's headers, snippet and labels; read the body with the Gmail actions. With your own Google OAuth app, Gmail needs a Pub/Sub topic: enter it and its push service account in the auth config, and point the topic's push subscription at the auth config's event URL.

Google Super: an account connected through Google Super has every Gmail, Google Calendar and Google Drive trigger, named after the app as its actions are: gmail_email_received, google_calendar_event_changed, google_drive_file_changed. The trigger and its events report the app they come from (connectorId: "gmail", event: "email_received"). With your own Google OAuth app, Gmail's push subscription points at https://api.dexby.ai/triggers/gmail/<auth config id>.

Jira: pass options: { "project": "ENG" }, the key of the project to watch. Dexby registers a webhook on the connected Jira site and extends it before Jira's 30-day expiry. Jira allows five triggers per connected account on a site. Accounts connected before triggers were added need to connect again, to grant the manage:jira-webhook permission. With your own Atlassian OAuth app, turn on sharing in its Distribution settings: Jira only delivers a private app's webhooks to the app's owner. An account connected through Atlassian Super has the same triggers, named jira_issue_created and so on.

Microsoft: Microsoft Graph names the changed item, so Dexby reads it and sends it: the email's sender, recipients, subject and preview (read the body with the Outlook actions), the calendar event, the Teams message, or the OneDrive file. Dexby renews Microsoft's subscription before it expires.

A Teams channel trigger needs the channel: pass options: { teamId, channelId }, from the list joined teams and list channels actions. Teams works with work or school accounts, and channel messages need an admin to consent to ChannelMessage.Read.All. An account connected through Microsoft Super has every Outlook, OneDrive and Teams trigger, named after the app: outlook_email_received, microsoft_teams_channel_message.

Zoom: an event reaches the account of the meeting's host. With your own Zoom app, set its event notification endpoint URL to the auth config's Event URL and enter the app's Secret token in the auth config before Zoom validates the URL. When a user removes the app in Zoom, Dexby deletes their Zoom connection and its triggers, and sends connection.deleted.

Asana: a trigger watches one project: pass options: { project }, the project's ID from its Asana URL. Dexby creates the Asana webhook and keeps the secret Asana signs it with. task_added and comment_added carry the whole task or comment; task_changed carries the task's ID and which field changed. Accounts connected before triggers existed must connect again to grant webhooks:write.

Dropbox: Dropbox only says which accounts changed, so Dexby reads each account's changes and sends one event per file or folder. Events carry the item's path and metadata, not its content. With your own Dropbox app, set its webhook URI to the auth config's Event URL; Dropbox signs with the app secret already in the auth config.

Calendly: a trigger receives the connected user's own bookings. data is Calendly's invitee: name, email, answers and the scheduled event. A reschedule sends invitee.canceled for the old time and invitee.created for the new one. Webhooks need a paid Calendly plan, and Calendly signs them with the OAuth app's Webhook signing key: with your own Calendly OAuth app, enter that key in the auth config. Accounts connected before triggers existed must connect again to grant webhooks:write.

Typeform: pass options: { formId }, the last part of the form's URL (u6nXL7). Dexby adds a webhook to that form and sends each submitted response, with its answers, as data. Accounts connected through OAuth before triggers existed must connect again to grant webhooks:write.

GitLab: pass options: { projectId }, the project's numeric ID or full path (acme/api). Dexby adds a project webhook for the one event, so the connected user needs the Maintainer or Owner role in that project. Works with GitLab.com and self-managed GitLab.

Box: pass options: { folderId }, the number at the end of the folder's Box URL. The trigger also covers every folder inside it. Box allows one trigger per folder for each connected account, and none on the root folder (0). Box signs deliveries with the OAuth app's Primary signature key: with your own Box app, enter it in the auth config. Accounts connected before triggers existed must connect again to grant manage_webhook.

ClickUp: pass options: { workspaceId }, the number right after app.clickup.com/ in the workspace's URL. Dexby creates the ClickUp webhook and keeps the secret ClickUp signs it with. task_created carries the whole task; the other task events carry history_items, what changed before and after.

Figma: pass options: { context, contextId }: context is team, project (a folder) or file, and contextId the team or folder number from its Figma URL, or the file key. Watching a team needs a team admin; a folder or file needs edit access. file_updated arrives after 30 minutes without edits. Accounts connected before triggers existed must connect again to grant webhooks:write.

Intercom: Intercom sends the topics ticked on the app's Webhooks page, from every workspace that installed the app, to one endpoint URL. Each event reaches the triggers of the workspace it came from; data is Intercom's data.item. With your own Intercom app, set the endpoint URL to the auth config's Event URL and tick each event's topic (named in its description, such as conversation.user.created). Intercom signs with the app's client secret, already in the auth config.

Airtable: pass options: { baseId, tableId }, the app… and tbl… parts of the table's URL. The connected user needs creator access to the base. Airtable only says that something changed, so Dexby reads what changed and sends Airtable's change payload: changedTablesById holds the created records with their cells, the changed cells before and after, or the deleted record IDs. Airtable allows two triggers per base for each OAuth app, and Dexby extends each one before Airtable's 7-day expiry. Accounts connected before triggers existed must connect again to grant webhook:manage.

Salesforce: Salesforce sends nothing without setup in the org, so Dexby reads it every 5 minutes and sends one event per new or changed record: an event arrives up to 6 minutes after the change. data is the whole record, and eventId the record's ID for the _created events. _updated covers records created before the trigger's last read, so a new record is not sent twice. Creating the trigger reads the org once, so an account that cannot read it fails then. When the org refuses the connection, Dexby sends connection.reauth_required and stops reading until it is connected again.

monday.com: pass options: { boardId }, the number in the board's URL. data is monday.com's event, and eventId its triggerUuid. monday.com signs deliveries with the app's Signing secret: with your own monday.com app, enter it in the auth config. Accounts connected before triggers existed must connect again to grant webhooks:write.

Events

EventWhendata
trigger.firedA trigger received an event.triggerId, connectorId, event, userId, connectionId, eventId, receivedAt, payload
connection.createdA user connected an account.connectionId, connectorId, userId, name
connection.deletedAn account was removed and its credential erased.connectionId, connectorId, userId
connection.reauth_requiredAn account needs reconnecting.connectionId, connectorId, userId
execution.failedA tool run failed.toolId, connectorId, userId, errorCode
mcp_server.tools_changedAn MCP server's tools changed.server, toolCount

For a global account, the connection.* events carry "userId": null and "global": true.

Every delivery has the shape { "type", "timestamp", "data" }. Payloads never include tool input or output, except the app's own payload in trigger.fired.

On this page