User guidesDeveloper platformLatest updatesSlack Community
User guides
Start typing to search…

Webhooks

Webhook Triggers

Webhook triggers allow your Dust agents to respond automatically to events in external systems. When something happens in another platform—a ticket is created, a PR is opened, a deal moves stages—your agent processes the event immediately with full company context.

How Webhook Triggers Work

Unlike schedules that run on a timeline, webhooks are event-driven:

  1. An event occurs in an external system (GitHub, Jira, Zendesk, or any custom platform)
  2. The system sends a webhook to Dust with event data
  3. Your agent is triggered and receives the event payload
  4. A new conversation starts where the agent can process the event and take action

Every webhook event creates a separate conversation, allowing your agent to handle each event independently with full context and reasoning transparency.

Built-in vs. Custom Webhooks

Dust provides two types of webhook integrations:

Built-in Webhook Providers

Pre-configured integrations with popular platforms that handle authentication and setup automatically:

  • GitHub: PR events, issue updates, code changes
  • Jira: Ticket creation, status changes, assignment updates
  • Zendesk: Support ticket events, customer interactions

Built-in providers offer:

  • OAuth authentication flow
  • Automatic webhook configuration
  • AI-powered filter generation (describe what you want in natural language)
  • Validated event schemas

Custom Webhooks

For any other platform that can send webhooks. Custom webhooks give you flexibility to integrate with:

  • Internal tools and services
  • Platforms without built-in Dust support
  • Custom applications and scripts

Custom webhooks require:

  • Manual webhook configuration in the source platform
  • Optional signature verification for security
  • Manual filter writing (if needed) using the webhook filter expression language

Setting Up Webhook Triggers

Webhook setup is a two-step process: workspace admins create webhook sources, then users add them to agents.

Step 1: Admin Creates a Webhook Source

Only workspace admins can create webhook sources. This ensures proper governance and security for incoming webhooks.

To create a webhook source:

  1. Navigate to Spaces → Triggers → Create Webhook Source

  2. Choose between a built-in provider or custom webhook

  3. Configure the webhook source:

    • Name: A descriptive name for the webhook source
    • Provider (built-in only): Select GitHub, Jira, or Zendesk
    • Authentication (built-in only): Complete OAuth flow to authorize Dust
    • Advanced settings (custom only):
      • Signature header: Header name for webhook signatures (e.g., X-Hub-Signature-256)
      • Signature algorithm: Choose sha1, sha256, or sha512
      • Secret: Shared secret for verifying webhook authenticity

  4. Save the webhook source

Dust generates a unique webhook URL and secret. For custom webhooks, you'll need to configure these in your source platform. For built-in providers, Dust handles this automatically.

Step 2: Users Add Webhook Triggers to Agents

Once a webhook source exists, any user can add it as a trigger to their agents:

  1. Open your agent in the Agent Builder

  2. Navigate to the Triggers section

  3. Select Add Webhook

  4. Configure the webhook trigger:

    • Select webhook source: Choose from available sources
    • Include payload: Whether to send event data to the agent (recommended)
    • Add filter (optional): Control which events trigger the agent

  5. Save your agent to activate the trigger

📘

Note

Webhook triggers are currently personal. Only the agent's creator can see triggered conversations.

Filtering Webhook Events

Real webhook streams are noisy. You don't want every event—you want specific events that matter to your workflow. Webhook filtering lets you specify exactly which events should trigger your agent.

Built-in Provider Filtering

For built-in providers (GitHub, Jira, Zendesk), describe your filtering criteria in natural language. Dust uses AI to generate the filter automatically.

Examples:

  • "Only when a PR is opened with more than 20 changed files"
  • "When a Jira ticket is created with priority 'High' or 'Critical'"
  • "When a Zendesk ticket contains the word 'urgent' and has no assignee"

The system translates your description into a precise filter that runs server-side, so your agent only wakes up for events that matter.

Custom Webhook Filtering

For custom webhooks, you write filters using the webhook filter expression language—a Lisp-style syntax that evaluates webhook payloads.

Learn the complete syntax in the Filter Webhooks Payload documentation.

No Filtering

If you don't add a filter, your agent triggers for every event from the webhook source. This is useful when you want the agent to process all events and make decisions based on its instructions.

Including Event Payloads

When creating a webhook trigger, you can choose whether to include the event payload in the conversation:

Include payload (recommended): The agent receives the full event data as structured JSON. Your agent's instructions can reference specific fields, make decisions based on event content, and extract relevant information.

Exclude payload: The agent is simply notified that an event occurred. Useful when you only need to trigger an action without processing event details.

Most workflows benefit from including the payload—it allows your agent to make context-aware decisions about how to respond.

Security and Authentication

Built-in Providers

Built-in providers use OAuth for authentication. When you create a webhook source, you'll authorize Dust to receive webhooks from your account. Dust handles:

  • Webhook registration with the provider
  • Signature verification
  • Event authentication
  • Token management

Custom Webhooks

For custom webhooks, security is optional but recommended:

  1. Webhook Secrets: Dust generates a secret when you create the webhook source. Configure your source platform to sign webhooks with this secret.

  2. Signature Verification: Specify the signature header name (e.g., X-Hub-Signature-256) and algorithm (sha1, sha256, or sha512). Dust verifies signatures automatically.

  3. URL Obscurity: Each webhook source gets a unique, unguessable URL that provides basic security through obscurity.

Monitoring Webhook Activity

Every webhook trigger creates a conversation you can review:

  • Triggered conversations appear in your conversations list with the agent
  • Event payload is visible in the conversation for debugging
  • Agent reasoning shows how the agent processed the event
  • Failed triggers are logged and visible for troubleshooting

For filtered webhooks, you can inspect which events matched your filter and which were ignored.

Best Practices

Start Simple

Begin with one webhook source and one agent. Verify it works before scaling to multiple workflows. Test with a few events before processing high-volume streams.

Use Filtering Wisely

Apply filters at the webhook level to reduce noise. Let your agent's instructions handle business logic. Don't replicate your agent's decision-making in filters—use filters to eliminate obvious irrelevant events.

Include Context in Instructions

Your agent's instructions should explain how to handle different event types. Reference specific payload fields by name. Provide examples of desired actions for common scenarios.

Plan for Failure

Events can arrive malformed or unexpected. Instruct your agent on how to handle edge cases. Monitor conversations regularly to catch issues early.

Iterate Based on Conversations

Review triggered conversations to understand what's working. Adjust filters, instructions, and tools based on actual event patterns. Let real data guide your workflow design.

Respect Rate Limits

High-volume webhooks can trigger many conversations. Be mindful of workspace fair use limits. Consider filtering or batching if you're processing hundreds of events per hour.

Limitations

  • Personal triggers: Webhook triggers are currently personal to the agent creator. Team-wide webhook triggers are coming soon.
  • One-way events: Webhook triggers create new conversations. Agents can't currently trigger future reminders or callbacks for themselves.
  • No app webhooks yet: Some platforms send webhooks through a single app for all workspaces (e.g., Notion, HubSpot). This pattern is not yet supported but is planned.

What's Next

Ready to connect your systems? Navigate to Spaces → Triggers to create your first webhook source, or open an agent in the Agent Builder to add a webhook trigger.

Updated about 2 hours ago