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
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.
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, orGET /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
| App | Events | Setup |
|---|---|---|
| Airtable | record_created, record_updated, record_deleted (needs baseId and tableId) | Automatic |
| Asana | task_added, task_changed, task_removed, task_deleted, comment_added (needs project) | Automatic |
| Box | file_uploaded, file_moved, file_renamed, file_trashed, file_restored, folder_created, comment_created (needs folderId) | Automatic |
| Calendly | invitee.created, invitee.canceled, invitee_no_show.created, invitee_no_show.deleted | Automatic |
| ClickUp | task_created, task_updated, task_status_updated, task_assignee_updated, task_moved, task_deleted, task_comment_posted, list_created (needs workspaceId) | Automatic |
| Dropbox | file_changed, folder_added, deleted | OAuth app |
| Figma | file_updated, file_version_updated, file_commented, file_deleted, library_published, dev_mode_status_updated (needs context, contextId) | Automatic |
| GitHub | push, pull_request_opened, pull_request_merged, pull_request_closed, issue_opened, issue_comment_created, release_published, workflow_run_completed | GitHub App |
| GitLab | push, tag_push, issue, merge_request, note, pipeline, job, release (needs projectId) | Automatic |
| Linear | issue_created, issue_updated, issue_removed, comment_created, project_updated | OAuth app |
| Gmail | email_received | OAuth app |
| Google Calendar | event_changed, event_cancelled | Automatic |
| Google Drive | file_changed, file_trashed, file_removed | Automatic |
| HubSpot | contact_created, contact_deleted, company_created, deal_created, deal_stage_changed, ticket_created | OAuth app |
| Intercom | conversation_created, conversation_user_replied, conversation_admin_replied, conversation_assigned, conversation_closed, contact_user_created, ticket_created | OAuth app |
| Jira | issue_created, issue_updated, issue_deleted, comment_created, comment_updated, comment_deleted (needs project) | Automatic |
| Microsoft Teams | chat_message, channel_message (needs teamId and channelId) | Automatic |
| monday.com | create_item, change_column_value, change_status_column_value, change_name, create_update, item_archived, item_deleted, create_subitem (needs boardId) | Automatic |
| OneDrive | file_changed, file_deleted | Automatic |
| Outlook | email_received, event_created, event_updated, event_deleted | Automatic |
| Notion | page_created, page_content_updated, page_properties_updated, page_deleted, comment_created | OAuth app |
| Salesforce | lead_created, lead_updated, and the same for contact, account, opportunity and case | Automatic |
| ShipStation | track, fulfillment_shipped_v2, fulfillment_rejected_v2, batch | Automatic |
| Slack | message, app_mention, reaction_added | Manual |
| Telegram | message, edited_message, channel_post, callback_query | Automatic |
| Typeform | form_response (needs formId) | Automatic |
| Zoom | meeting_created, meeting_updated, meeting_deleted, meeting_started, meeting_ended, participant_joined, participant_left, recording_completed, transcript_completed | OAuth app |
| WooCommerce | order.created, order.updated, product.created, product.updated, customer.created | Automatic |
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
| Event | When | data |
|---|---|---|
trigger.fired | A trigger received an event. | triggerId, connectorId, event, userId, connectionId, eventId, receivedAt, payload |
connection.created | A user connected an account. | connectionId, connectorId, userId, name |
connection.deleted | An account was removed and its credential erased. | connectionId, connectorId, userId |
connection.reauth_required | An account needs reconnecting. | connectionId, connectorId, userId |
execution.failed | A tool run failed. | toolId, connectorId, userId, errorCode |
mcp_server.tools_changed | An 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.