Triggers and webhooks

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.

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 })
}

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)

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 triggersCopy Anchor Link

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.harryy.ai/triggers/gmail/<auth config id>.

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.

EventsCopy Anchor Link

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.