Skip to content

docs: restore Brex, Composio and Intercom webhook provider pages - #5131

Draft
jackbridger wants to merge 37 commits into
mainfrom
docs/webhooks-restore-providers
Draft

jackbridger wants to merge 37 commits into
mainfrom
docs/webhooks-restore-providers

Conversation

@jackbridger

Copy link
Copy Markdown
Collaborator

Summary

Brings back the Brex, Composio and Intercom provider pages that #5124 left out, now that their setup works:

  • Brex verifies the Standard Webhooks headers Brex sends (webhook-id, webhook-timestamp, webhook-signature). Setup uses Brex's API, since it has no webhook settings page.
  • Composio keys the signature with the secret's raw text, as Composio signs it. Setup registers the URL with Composio's webhook subscription API.
  • Intercom uses the app's client secret, and endpoints now answer Intercom's HEAD check on the URL.

The providers table, sidebar and deduplication table include them again, and their redirects to the providers list are removed.

Merge after the release that ships the Brex and Composio verification fixes (@trigger.dev/sdk 4.8.6) and the deploy that answers HEAD requests. The Brex and Composio pages note the SDK version.

Stacked on #5124.

- Add a page for each built-in provider source under Webhooks > Providers,
  with an index of every source and its credential
- Add a quick start, a custom providers page split out of sources, and a
  page on using your own handler
- Fold the public beta page into the overview
- Rename the Next.js and Remix webhook guides to custom handler guides,
  move them under Frameworks, and point readers to hosted endpoints
- Remove the Guides > Webhooks group; redirect the old overview, Stripe and
  Hookdeck guides to the new pages
Move the How it works and Pricing and limits sections to their own pages,
drop the Connect it section, and cut the overview's card grid to three.
Say provider for the external service and source only for the endpoint's
source field. Redirect /webhooks/sources to /webhooks/verification.
Connect a provider now covers only registering the URL and credential and
checking delivery. Rotation, CLI, MCP and REST secret management move to a
Signing secrets page, and the WhatsApp verify token moves to its provider
page. Verification moves below Providers in the sidebar.
Explain the request lifecycle (verify, dedupe, store, answer, route),
endpoints declared in code, shared endpoints with many subscribers,
two-layer deduplication, and recorded deliveries.
… Agents

Add a Channels group to the Agents section for the channel pages, and move
Session routing into the Webhooks Handle events group. Page URLs are
unchanged.
Add Named providers and Custom providers sections to Verification so
old /webhooks/sources anchors land on them, expand the Stripe provider
page with Dashboard setup, local testing and an own-route section, and
redirect /examples/stripe-webhook and /examples/hookdeck-webhook directly.
Use provider for the service and source for the code value, keep the
credential and subscriber tables in one place each, complete the
deduplication key table, drop Stripe from the examples cards, rename
stale webhook handler cards, and update dead or moved provider docs links.
Fix the removed-headers, channel replay targetId and deliveryId notes,
set Discord's public key before saving the URL, and rewrite setup for
Vapi, Replicate, Retell AI, Brex, Calendly, DocuSign, Autumn and
Recall.ai from each provider's current docs.
webhooks.zoom() isn't exported by the SDK yet, so drop the page, its
providers table row and sidebar entry, and redirect the URL to the
providers list.
Carry the additionalSignatureHeaders option for custom HMAC providers
over from the removed sources page, and merge the two overlapping test
steps on the Loops, Tailscale and PlanetScale pages.
Give each provider page its own description and opener naming the
signature it checks, label the settings table, and remove filler
wording from the channels, session routing, Slack, Linear and channel
human-in-the-loop pages.
Setup can't be completed for these providers yet, so drop their pages,
table rows and sidebar entries, redirect the URLs to the providers list,
and update the provider counts.
Replace the conditional secret step on the Attio, Cal.com, Jira, Linear,
PagerDuty, Sentry, Typeform, Vercel and Zendesk pages with each
provider's actual flow and menu path.
Add the confirm step for Generate secret, the x-github-event header in
the Test tab, deduplication of repeated test bodies, and the Targets
view on a delivery, from a run-through on a fresh project.
Keep batched bodies intact in the Hookdeck transformation, drop the
Stripe-only filter from the generic Hookdeck example, add Slack's
install step and Typeform's On switch, filter Zendesk on event.type,
correct retry, header and ordering wording, and remove the Composio
page until its secret format is supported.
Send the wrapped body as JSON, accept any payload type, and require
authentication on the Hookdeck source.
Bring the three pages back now that their verification and URL checks
are fixed: Brex reads the Standard Webhooks headers, Composio keys the
signature with the raw secret, and endpoints answer Intercom's HEAD
check.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Walkthrough

The documentation reorganizes webhook navigation and adds hosted endpoint quick-start, processing, verification, credential, and provider setup guides. It adds setup documentation for many built-in providers and custom providers. It also updates webhook task, waiter, delivery, pricing, and limit references. Framework webhook guides now describe custom handlers, while separate pages cover hosted endpoints and agent channels. Several older webhook guides are removed, and redirects point legacy URLs to replacement pages.

Merge Risk: Moderate · up to 1ade1

These pages restore and add webhook setup docs, and a few steps could mislead users. Adding a second DocuSign key, an unauthenticated Hookdeck source, and Vapi events that need a response can each leave setups broken or insecure. Fix these before merging; the remaining wording corrections are minor.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title "docs: restore Brex, Composio and Intercom webhook provider pages" matches the main change. The PR restores the Brex, Composio, and Intercom provider pages and their entries in the providers…
Description check Passed The description follows the template's structure only in part. It has a Summary section that explains what is restored and why, and it gives the verification and setup details for each provider. It al…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title "docs: restore Brex, Composio and Intercom webhook provider pages" matches the main change. The PR restores the Brex, Composio, and Intercom provider pages and their entries in the providers table, sidebar, and deduplication table, and removes their redirects. The title uses the repository's docs prefix and names the specific providers.

Full details: Description check

Explanation

The description follows the template's structure only in part. It has a Summary section that explains what is restored and why, and it gives the verification and setup details for each provider. It also says to merge after the SDK 4.8.6 release and the HEAD-request deploy, and it states the stacking on #5124. The template's Checklist, Testing, Changelog, and Screenshots sections are missing. The template's 'Closes #<issue>' line is also missing.

Resolution

Consider adding the template sections the description omits: a 'Closes #<issue>' line if an issue applies, the checklist, a Testing section that describes how the provider pages and setup were verified, a Changelog entry, and Screenshots if the docs pages changed visually. The summary already covers the substance, so these are non-critical gaps.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@changeset-bot

changeset-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 1ade15a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Base automatically changed from docs/webhooks-restructure to main November 17, 2026 10:48

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8

Review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 9bb1c3f7-06ad-42a8-9818-ab8003742c52
Commits

Reviewing files that changed from the base of the PR and between 110f6d8 and 1ade15a.

Files selected for processing: 77

  • docs/docs.json
  • docs/guides/example-projects/resend-email-agent.mdx
  • docs/guides/examples/hookdeck-webhook.mdx
  • docs/guides/examples/stripe-webhook.mdx
  • docs/guides/frameworks/nextjs-webhooks.mdx
  • docs/guides/frameworks/remix-webhooks.mdx
  • docs/guides/frameworks/remix.mdx
  • docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx
  • docs/guides/frameworks/webhooks-guides-overview.mdx
  • docs/guides/introduction.mdx
  • docs/snippets/examples-cards.mdx
  • docs/snippets/vercel-docs-cards.mdx
  • docs/webhooks/channels.mdx
  • docs/webhooks/connect.mdx
  • docs/webhooks/custom-providers.mdx
  • docs/webhooks/deliveries.mdx
  • docs/webhooks/filters.mdx
  • docs/webhooks/how-it-works.mdx
  • docs/webhooks/human-in-the-loop.mdx
  • docs/webhooks/linear.mdx
  • docs/webhooks/overview.mdx
  • docs/webhooks/own-handler.mdx
  • docs/webhooks/pricing-and-limits.mdx
  • docs/webhooks/providers.mdx
  • docs/webhooks/providers/attio.mdx
  • docs/webhooks/providers/autumn.mdx
  • docs/webhooks/providers/brex.mdx
  • docs/webhooks/providers/cal-com.mdx
  • docs/webhooks/providers/calendly.mdx
  • docs/webhooks/providers/clerk.mdx
  • docs/webhooks/providers/composio.mdx
  • docs/webhooks/providers/discord.mdx
  • docs/webhooks/providers/docusign.mdx
  • docs/webhooks/providers/elevenlabs.mdx
  • docs/webhooks/providers/firecrawl.mdx
  • docs/webhooks/providers/github.mdx
  • docs/webhooks/providers/gitlab.mdx
  • docs/webhooks/providers/granola.mdx
  • docs/webhooks/providers/hookdeck.mdx
  • docs/webhooks/providers/infisical.mdx
  • docs/webhooks/providers/intercom.mdx
  • docs/webhooks/providers/jira.mdx
  • docs/webhooks/providers/langfuse.mdx
  • docs/webhooks/providers/linear.mdx
  • docs/webhooks/providers/loops.mdx
  • docs/webhooks/providers/metronome.mdx
  • docs/webhooks/providers/mux.mdx
  • docs/webhooks/providers/openai.mdx
  • docs/webhooks/providers/pagerduty.mdx
  • docs/webhooks/providers/plain.mdx
  • docs/webhooks/providers/planetscale.mdx
  • docs/webhooks/providers/recall-ai.mdx
  • docs/webhooks/providers/replicate.mdx
  • docs/webhooks/providers/resend.mdx
  • docs/webhooks/providers/retell.mdx
  • docs/webhooks/providers/sentry.mdx
  • docs/webhooks/providers/shopify.mdx
  • docs/webhooks/providers/slack.mdx
  • docs/webhooks/providers/square.mdx
  • docs/webhooks/providers/stripe.mdx
  • docs/webhooks/providers/supabase.mdx
  • docs/webhooks/providers/tailscale.mdx
  • docs/webhooks/providers/typeform.mdx
  • docs/webhooks/providers/vapi.mdx
  • docs/webhooks/providers/vercel.mdx
  • docs/webhooks/providers/whatsapp.mdx
  • docs/webhooks/providers/workos.mdx
  • docs/webhooks/providers/zendesk.mdx
  • docs/webhooks/public-beta.mdx
  • docs/webhooks/quick-start.mdx
  • docs/webhooks/session-routing.mdx
  • docs/webhooks/signing-secrets.mdx
  • docs/webhooks/slack.mdx
  • docs/webhooks/sources.mdx
  • docs/webhooks/verification.mdx
  • docs/webhooks/waiters.mdx
  • docs/webhooks/webhook-tasks.mdx
Files with no reviewable changes: 5

  • docs/guides/examples/hookdeck-webhook.mdx
  • docs/guides/examples/stripe-webhook.mdx
  • docs/guides/frameworks/webhooks-guides-overview.mdx
  • docs/webhooks/public-beta.mdx
  • docs/webhooks/sources.mdx

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

Review details

Additional context used

Code guidelines: 3

docs/AGENTS.md — auto-discovered
.claude/rules/docs-writing.md — auto-discovered
.cursor/rules/writing-tasks.mdc — auto-discovered
Path-based instructions: 3

Applicability reference: AGENTS.md: # AGENTS.md Docs live in `docs/` as a Mintlify site (MDX format).

CodeRabbit inference engine (docs/AGENTS.md)

Files:

  • docs/guides/example-projects/resend-email-agent.mdx
  • docs/guides/frameworks/nextjs-webhooks.mdx
  • docs/guides/frameworks/remix-webhooks.mdx
  • docs/guides/frameworks/remix.mdx
  • docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx
  • docs/guides/introduction.mdx
  • docs/snippets/examples-cards.mdx
  • docs/snippets/vercel-docs-cards.mdx
  • docs/webhooks/channels.mdx
  • docs/webhooks/connect.mdx
  • docs/webhooks/custom-providers.mdx
  • docs/webhooks/deliveries.mdx
  • docs/webhooks/filters.mdx
  • docs/webhooks/how-it-works.mdx
  • docs/webhooks/human-in-the-loop.mdx
  • docs/webhooks/linear.mdx
  • docs/webhooks/overview.mdx
  • docs/webhooks/own-handler.mdx
  • docs/webhooks/pricing-and-limits.mdx
  • docs/webhooks/providers.mdx
  • docs/webhooks/providers/attio.mdx
  • docs/webhooks/providers/autumn.mdx
  • docs/webhooks/providers/brex.mdx
  • docs/webhooks/providers/cal-com.mdx
  • docs/webhooks/providers/calendly.mdx
  • docs/webhooks/providers/clerk.mdx
  • docs/webhooks/providers/composio.mdx
  • docs/webhooks/providers/discord.mdx
  • docs/webhooks/providers/docusign.mdx
  • docs/webhooks/providers/elevenlabs.mdx
  • docs/webhooks/providers/firecrawl.mdx
  • docs/webhooks/providers/github.mdx
  • docs/webhooks/providers/gitlab.mdx
  • docs/webhooks/providers/granola.mdx
  • docs/webhooks/providers/hookdeck.mdx
  • docs/webhooks/providers/infisical.mdx
  • docs/webhooks/providers/intercom.mdx
  • docs/webhooks/providers/jira.mdx
  • docs/webhooks/providers/langfuse.mdx
  • docs/webhooks/providers/linear.mdx
  • docs/webhooks/providers/loops.mdx
  • docs/webhooks/providers/metronome.mdx
  • docs/webhooks/providers/mux.mdx
  • docs/webhooks/providers/openai.mdx
  • docs/webhooks/providers/pagerduty.mdx
  • docs/webhooks/providers/plain.mdx
  • docs/webhooks/providers/planetscale.mdx
  • docs/webhooks/providers/recall-ai.mdx
  • docs/webhooks/providers/replicate.mdx
  • docs/webhooks/providers/resend.mdx
  • docs/webhooks/providers/retell.mdx
  • docs/webhooks/providers/sentry.mdx
  • docs/webhooks/providers/shopify.mdx
  • docs/webhooks/providers/slack.mdx
  • docs/webhooks/providers/square.mdx
  • docs/webhooks/providers/stripe.mdx
  • docs/webhooks/providers/supabase.mdx
  • docs/webhooks/providers/tailscale.mdx
  • docs/webhooks/providers/typeform.mdx
  • docs/webhooks/providers/vapi.mdx
  • docs/webhooks/providers/vercel.mdx
  • docs/webhooks/providers/whatsapp.mdx
  • docs/webhooks/providers/workos.mdx
  • docs/webhooks/providers/zendesk.mdx
  • docs/webhooks/quick-start.mdx
  • docs/webhooks/session-routing.mdx
  • docs/webhooks/signing-secrets.mdx
  • docs/webhooks/slack.mdx
  • docs/webhooks/verification.mdx
  • docs/webhooks/waiters.mdx
  • docs/webhooks/webhook-tasks.mdx
Source excerpt: Use Mintlify MDX format.

CodeRabbit inference engine (.claude/rules/docs-writing.md)

Files:

  • docs/docs.json
  • docs/guides/example-projects/resend-email-agent.mdx
  • docs/guides/frameworks/nextjs-webhooks.mdx
  • docs/guides/frameworks/remix-webhooks.mdx
  • docs/guides/frameworks/remix.mdx
  • docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx
  • docs/guides/introduction.mdx
  • docs/snippets/examples-cards.mdx
  • docs/snippets/vercel-docs-cards.mdx
  • docs/webhooks/channels.mdx
  • docs/webhooks/connect.mdx
  • docs/webhooks/custom-providers.mdx
  • docs/webhooks/deliveries.mdx
  • docs/webhooks/filters.mdx
  • docs/webhooks/how-it-works.mdx
  • docs/webhooks/human-in-the-loop.mdx
  • docs/webhooks/linear.mdx
  • docs/webhooks/overview.mdx
  • docs/webhooks/own-handler.mdx
  • docs/webhooks/pricing-and-limits.mdx
  • docs/webhooks/providers.mdx
  • docs/webhooks/providers/attio.mdx
  • docs/webhooks/providers/autumn.mdx
  • docs/webhooks/providers/brex.mdx
  • docs/webhooks/providers/cal-com.mdx
  • docs/webhooks/providers/calendly.mdx
  • docs/webhooks/providers/clerk.mdx
  • docs/webhooks/providers/composio.mdx
  • docs/webhooks/providers/discord.mdx
  • docs/webhooks/providers/docusign.mdx
  • docs/webhooks/providers/elevenlabs.mdx
  • docs/webhooks/providers/firecrawl.mdx
  • docs/webhooks/providers/github.mdx
  • docs/webhooks/providers/gitlab.mdx
  • docs/webhooks/providers/granola.mdx
  • docs/webhooks/providers/hookdeck.mdx
  • docs/webhooks/providers/infisical.mdx
  • docs/webhooks/providers/intercom.mdx
  • docs/webhooks/providers/jira.mdx
  • docs/webhooks/providers/langfuse.mdx
  • docs/webhooks/providers/linear.mdx
  • docs/webhooks/providers/loops.mdx
  • docs/webhooks/providers/metronome.mdx
  • docs/webhooks/providers/mux.mdx
  • docs/webhooks/providers/openai.mdx
  • docs/webhooks/providers/pagerduty.mdx
  • docs/webhooks/providers/plain.mdx
  • docs/webhooks/providers/planetscale.mdx
  • docs/webhooks/providers/recall-ai.mdx
  • docs/webhooks/providers/replicate.mdx
  • docs/webhooks/providers/resend.mdx
  • docs/webhooks/providers/retell.mdx
  • docs/webhooks/providers/sentry.mdx
  • docs/webhooks/providers/shopify.mdx
  • docs/webhooks/providers/slack.mdx
  • docs/webhooks/providers/square.mdx
  • docs/webhooks/providers/stripe.mdx
  • docs/webhooks/providers/supabase.mdx
  • docs/webhooks/providers/tailscale.mdx
  • docs/webhooks/providers/typeform.mdx
  • docs/webhooks/providers/vapi.mdx
  • docs/webhooks/providers/vercel.mdx
  • docs/webhooks/providers/whatsapp.mdx
  • docs/webhooks/providers/workos.mdx
  • docs/webhooks/providers/zendesk.mdx
  • docs/webhooks/quick-start.mdx
  • docs/webhooks/session-routing.mdx
  • docs/webhooks/signing-secrets.mdx
  • docs/webhooks/slack.mdx
  • docs/webhooks/verification.mdx
  • docs/webhooks/waiters.mdx
  • docs/webhooks/webhook-tasks.mdx
Source excerpt: You MUST import from `@trigger.dev/sdk` (NEVER `@trigger.dev/sdk/v3`) Source excerpt: You MUST NEVER use `client.defineJob` Source excerpt: YOU MUST `export` every task, including subtasks Source excerpt: Key points: Each ta...

CodeRabbit inference engine (.cursor/rules/writing-tasks.mdc)

Files:

  • docs/docs.json
  • docs/guides/example-projects/resend-email-agent.mdx
  • docs/guides/frameworks/nextjs-webhooks.mdx
  • docs/guides/frameworks/remix-webhooks.mdx
  • docs/guides/frameworks/remix.mdx
  • docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx
  • docs/guides/introduction.mdx
  • docs/snippets/examples-cards.mdx
  • docs/snippets/vercel-docs-cards.mdx
  • docs/webhooks/channels.mdx
  • docs/webhooks/connect.mdx
  • docs/webhooks/custom-providers.mdx
  • docs/webhooks/deliveries.mdx
  • docs/webhooks/filters.mdx
  • docs/webhooks/how-it-works.mdx
  • docs/webhooks/human-in-the-loop.mdx
  • docs/webhooks/linear.mdx
  • docs/webhooks/overview.mdx
  • docs/webhooks/own-handler.mdx
  • docs/webhooks/pricing-and-limits.mdx
  • docs/webhooks/providers.mdx
  • docs/webhooks/providers/attio.mdx
  • docs/webhooks/providers/autumn.mdx
  • docs/webhooks/providers/brex.mdx
  • docs/webhooks/providers/cal-com.mdx
  • docs/webhooks/providers/calendly.mdx
  • docs/webhooks/providers/clerk.mdx
  • docs/webhooks/providers/composio.mdx
  • docs/webhooks/providers/discord.mdx
  • docs/webhooks/providers/docusign.mdx
  • docs/webhooks/providers/elevenlabs.mdx
  • docs/webhooks/providers/firecrawl.mdx
  • docs/webhooks/providers/github.mdx
  • docs/webhooks/providers/gitlab.mdx
  • docs/webhooks/providers/granola.mdx
  • docs/webhooks/providers/hookdeck.mdx
  • docs/webhooks/providers/infisical.mdx
  • docs/webhooks/providers/intercom.mdx
  • docs/webhooks/providers/jira.mdx
  • docs/webhooks/providers/langfuse.mdx
  • docs/webhooks/providers/linear.mdx
  • docs/webhooks/providers/loops.mdx
  • docs/webhooks/providers/metronome.mdx
  • docs/webhooks/providers/mux.mdx
  • docs/webhooks/providers/openai.mdx
  • docs/webhooks/providers/pagerduty.mdx
  • docs/webhooks/providers/plain.mdx
  • docs/webhooks/providers/planetscale.mdx
  • docs/webhooks/providers/recall-ai.mdx
  • docs/webhooks/providers/replicate.mdx
  • docs/webhooks/providers/resend.mdx
  • docs/webhooks/providers/retell.mdx
  • docs/webhooks/providers/sentry.mdx
  • docs/webhooks/providers/shopify.mdx
  • docs/webhooks/providers/slack.mdx
  • docs/webhooks/providers/square.mdx
  • docs/webhooks/providers/stripe.mdx
  • docs/webhooks/providers/supabase.mdx
  • docs/webhooks/providers/tailscale.mdx
  • docs/webhooks/providers/typeform.mdx
  • docs/webhooks/providers/vapi.mdx
  • docs/webhooks/providers/vercel.mdx
  • docs/webhooks/providers/whatsapp.mdx
  • docs/webhooks/providers/workos.mdx
  • docs/webhooks/providers/zendesk.mdx
  • docs/webhooks/quick-start.mdx
  • docs/webhooks/session-routing.mdx
  • docs/webhooks/signing-secrets.mdx
  • docs/webhooks/slack.mdx
  • docs/webhooks/verification.mdx
  • docs/webhooks/waiters.mdx
  • docs/webhooks/webhook-tasks.mdx
Learnings: 5

Common learnings

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: docs/AGENTS.md:0-0
Timestamp: 2026-10-27T18:01:18.763Z
Learning: Applies to docs/**/*.mdx : Applicability reference:
AGENTS.md: # AGENTS.md
## Architecture Overview
### Documentation
Docs live in `docs/` as a Mintlify site (MDX format). See `docs/AGENTS.md` for conventions.

Source excerpt:
# Documentation

## Adding a New Page

2. Add the page path to `docs.json` navigation (under the correct group)
Learning: 2026-10-27T18:01:18.763Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: docs/AGENTS.md:0-0
Timestamp: 2026-10-27T18:01:18.763Z
Learning: Applies to docs/**/*.mdx : Applicability reference:
AGENTS.md: # AGENTS.md
## Architecture Overview
### Documentation
Docs live in `docs/` as a Mintlify site (MDX format). See `docs/AGENTS.md` for conventions.

Source excerpt:
# Documentation

## Code Examples

- Always import from `trigger.dev/sdk` (never `trigger.dev/sdk/v3`)

Applied to files:

  • docs/webhooks/custom-providers.mdx
  • docs/webhooks/providers/brex.mdx
  • docs/webhooks/providers/docusign.mdx
  • docs/webhooks/providers/infisical.mdx
  • docs/webhooks/providers/intercom.mdx
  • docs/webhooks/providers/metronome.mdx
  • docs/webhooks/providers/mux.mdx
  • docs/webhooks/providers/whatsapp.mdx
  • docs/webhooks/providers/zendesk.mdx
Learning: 2026-04-30T20:30:29.458Z

Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3226
File: docs/ai-chat/quick-start.mdx:13-13
Timestamp: 2026-04-30T20:30:29.458Z
Learning: In this repo’s documentation MDX files (`docs/**/*.mdx`), use `ts` and `tsx` (not `typescript`) as the code-fence language tags for TypeScript/TSX snippets. Do not flag `ts`/`tsx` code-fence language tags as incorrect in any docs MDX file, since this is the site-wide Mintlify-compatible convention.

Applied to files:

  • docs/webhooks/custom-providers.mdx
  • docs/webhooks/own-handler.mdx
  • docs/webhooks/providers/attio.mdx
  • docs/webhooks/providers/brex.mdx
  • docs/webhooks/providers/cal-com.mdx
  • docs/webhooks/providers/calendly.mdx
  • docs/webhooks/providers/clerk.mdx
  • docs/webhooks/providers/composio.mdx
  • docs/webhooks/providers/discord.mdx
  • docs/webhooks/providers/docusign.mdx
  • docs/webhooks/providers/elevenlabs.mdx
  • docs/webhooks/providers/firecrawl.mdx
  • docs/webhooks/providers/github.mdx
  • docs/webhooks/providers/gitlab.mdx
  • docs/webhooks/providers/granola.mdx
  • docs/webhooks/providers/intercom.mdx
  • docs/webhooks/providers/jira.mdx
  • docs/webhooks/providers/langfuse.mdx
  • docs/webhooks/providers/linear.mdx
  • docs/webhooks/providers/loops.mdx
  • docs/webhooks/providers/mux.mdx
  • docs/webhooks/providers/openai.mdx
  • docs/webhooks/providers/pagerduty.mdx
  • docs/webhooks/providers/plain.mdx
  • docs/webhooks/providers/planetscale.mdx
  • docs/webhooks/providers/recall-ai.mdx
  • docs/webhooks/providers/retell.mdx
  • docs/webhooks/providers/sentry.mdx
  • docs/webhooks/providers/shopify.mdx
  • docs/webhooks/providers/slack.mdx
  • docs/webhooks/providers/stripe.mdx
  • docs/webhooks/providers/supabase.mdx
  • docs/webhooks/providers/typeform.mdx
  • docs/webhooks/providers/vercel.mdx
  • docs/webhooks/providers/whatsapp.mdx
  • docs/webhooks/providers/workos.mdx
  • docs/webhooks/providers/zendesk.mdx
  • docs/webhooks/quick-start.mdx
  • docs/webhooks/verification.mdx
Learning: 2026-10-11T17:53:54.634Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-10-11T17:53:54.634Z
Learning: Source excerpt:
# AGENTS.md

## Writing Trigger.dev Tasks

Always import from `trigger.dev/sdk`. Never use `trigger.dev/sdk/v3` or deprecated `client.defineJob`.

```typescript
import { task } from "trigger.dev/sdk";

export const myTask = task({
  id: "my-task",
  run: async (payload: { message: string }) => {
    // Task logic
  },
});
```

Applied to files:

  • docs/webhooks/own-handler.mdx
  • docs/webhooks/providers/discord.mdx
  • docs/webhooks/providers/firecrawl.mdx
  • docs/webhooks/providers/infisical.mdx
  • docs/webhooks/providers/intercom.mdx
  • docs/webhooks/providers/langfuse.mdx
  • docs/webhooks/providers/zendesk.mdx
Learning: 2026-10-27T17:56:45.137Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2026-10-27T17:56:45.137Z
Learning: Applies to ** : Source excerpt:
# How to write Trigger.dev tasks

## Essential requirements when generating task code

1. You MUST import from `trigger.dev/sdk` (NEVER `trigger.dev/sdk/v3`)

Applied to files:

  • docs/webhooks/own-handler.mdx
  • docs/webhooks/providers/autumn.mdx
  • docs/webhooks/providers/cal-com.mdx
  • docs/webhooks/providers/calendly.mdx
  • docs/webhooks/providers/composio.mdx
  • docs/webhooks/providers/discord.mdx
  • docs/webhooks/providers/docusign.mdx
  • docs/webhooks/providers/hookdeck.mdx
  • docs/webhooks/providers/jira.mdx
  • docs/webhooks/providers/langfuse.mdx
  • docs/webhooks/providers/metronome.mdx
  • docs/webhooks/providers/planetscale.mdx
  • docs/webhooks/providers/sentry.mdx
  • docs/webhooks/providers/zendesk.mdx
LanguageTool

docs/webhooks/linear.mdx

[uncategorized] ~112-~112: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...ns. The card lays the tool input out as markdown: a list of proposed items becomes a num...

(MARKDOWN_NNP)

docs/webhooks/providers/cal-com.mdx

[grammar] ~40-~40: Ensure spelling is correct
Context: ...it, Cal.com doesn't sign deliveries and every one is rejected. Cal.com hides the secret a...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

docs/webhooks/providers/composio.mdx

[grammar] ~40-~40: Ensure spelling is correct
Context: ...ers/subscribing-to-events) | ## Set up Composio 1. Start trigger dev or deploy, then copy...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

docs/webhooks/providers/docusign.mdx

[grammar] ~40-~40: Ensure spelling is correct
Context: ...t, DocuSign doesn't sign deliveries and every one is rejected. 4. Send a test event from ...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

docs/webhooks/providers/hookdeck.mdx

[style] ~66-~66: To elevate your writing, try using more formal phrasing here.
Context: ...X-Hookdeck-Signature-2, so deliveries keep verifying until you store the new secret. - **Ded...

(CONTINUE_TO_VB)


[grammar] ~74-~74: Use a hyphen to join words.
Context: ...oken** authentication using a Trigger only environment API key. 2...

(QB_NEW_EN_HYPHEN)

Additional comments: 10

docs/webhooks/pricing-and-limits.mdx: 1

9-9: Functional Correctness

The claimed discrepancy is not established. The 5-second exemption in docs/run-usage.mdx applies to wait.for and wait.until. The webhook waiter is a waitpoint, and the inspected docs do not apply that threshold to it. The pricing page's statement that a waiting run uses no compute therefore does not conflict with the usage reference. The open question about sub-5-second webhook waits is a documentation gap, not a demonstrated error.

docs/webhooks/providers.mdx: 1

27-27: Functional Correctness

The Intercom setup can be completed in the dashboard. SetSecretDialog is rendered for every endpoint, including integrator-mode endpoints such as Intercom, so the app's client secret can be pasted. The concern that only Generate secret is offered is contradicted by route.tsx:613-624.

docs/webhooks/providers/attio.mdx: 1

37-37: Functional Correctness

The Attio signing-secret step is not blocked. The route gates only the Generate/Regenerate block on secretProvisioning, and the paste path for provider-issued secrets is not excluded for integrator endpoints. Users can paste the secret Attio issues.

docs/webhooks/providers/composio.mdx: 1

10-10: Data Integrity & Integration

The comment asks whether SDK 4.8.6 changes Composio's key handling, and it does not state a defect in the checked-out code. It cannot be decided from the repository.

The checkout shows that webhooks.composio() inherits a base64 secret transform. Whether that transform rejects valid Composio deliveries depends on two facts the checkout does not establish:

  1. Composio signs with the raw UTF-8 bytes of the secret, and does not use a whsec_<base64> secret.
  2. The transform, as implemented, does not decode or reject a value without the whsec_ prefix in a way that breaks verification.

The release-artifact check the comment proposes cannot be performed from this checkout. Keep the release gate in the PR. This decision needs the Composio signing contract and the transform implementation.

docs/webhooks/providers/brex.mdx: 1

10-10: Data Integrity & Integration

The Brex page already requires @trigger.dev/sdk 4.8.6 or later. At this head, the SDK's Brex source still uses the svix verifier preset, so 4.8.5 is not a valid Brex configuration. The page does not offer 4.8.5 for Brex, so the documentation is not wrong about it.

Whether 4.8.6 fixes the header handling is a claim about an unreleased artifact. Neither the checkout nor the PR shows evidence that 4.8.6 still fails. The concern therefore has no supported documentation defect at this head. The author's merge gate on 4.8.6 already covers the remaining release check.

docs/webhooks/providers/intercom.mdx: 1

40-40: Functional Correctness

The Intercom setup text correctly states Intercom's HEAD requirement. No change to docs/webhooks/providers/intercom.mdx is needed for this concern. Whether the hosted endpoint answers HEAD requests before merge is a release-sequencing question that the PR already addresses.

docs/webhooks/providers/pagerduty.mdx: 1

39-39: Functional Correctness

The concern is refuted. For integrator-provisioned endpoints, the dashboard renders the Set signing secret control as well as Generate secret. Readers can store PagerDuty's issued secret and complete the setup in line 39.

docs/webhooks/providers/sentry.mdx: 1

40-40: Functional Correctness

The integrator classification enables Generate secret for Sentry. It does not remove Set signing secret. The Sentry setup flow can complete with the existing Client Secret.

docs/webhooks/own-handler.mdx: 2

51-51: Security & Privacy

The Trigger only key matches the restriction described in the webhook guidance. The documented scope allows triggering runs and batches, plus uploading large payloads for those triggers. The docs do not list any other action, so the example does not mislead readers about the key's permissions.


7-7: Data Integrity & Integration

The hosted endpoint does not route a Stripe retry with the same event ID twice. The duplicate check comes from the front gate, and the Run Engine key covers task routing.

The Stripe key is the body id. Retries reuse that key. A promoted duplicate returns early. A claimed-but-unpromoted duplicate requeues the same job id. Task fan-out sets a stable idempotencyKey from the endpoint and delivery key, with a three-day expiry for Stripe.

description: "Receive webhooks in a route in your own app and trigger tasks from it with tasks.trigger()."
---

**Trigger.dev has built-in webhook endpoints, and we recommend them for most projects.** They verify each provider's signature, drop duplicate retries, record every delivery, and route events to tasks, agents and waiting runs. See [Webhooks](/webhooks/overview).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Supported by static analysis

Script executed:

rg -n -F --glob '*.ts' -e 'verification_failed' -e 'webhookEngine' -e 'ingest(' -- apps/ packages/ internal-packages/ || test "$?" -eq 1

Repository: triggerdotdev/trigger.dev

Length of output: 27422


Script executed:

cat -n internal-packages/webhook-engine/src/engine/index.ts | sed -n '366,460p'
echo '--- route ---'
cat -n 'apps/webapp/app/routes/webhooks.v1.ingest.$opaqueId.ts' | sed -n '30,70p'
echo '--- tests ---'
cat -n internal-packages/webhook-engine/src/engine/ingest.test.ts | sed -n '495,520p'
cat -n internal-packages/webhook-engine/src/engine/ingest.test.ts | sed -n '1560,1600p'

Repository: triggerdotdev/trigger.dev

Length of output: 9748


Clarify that the delivery record covers accepted deliveries only.

The hosted endpoints do not create a delivery record for a request that fails signature verification. The ingress logs that request and returns a rejection. Readers who expect every incoming request in delivery history can be misled. Replace "every delivery" with "every accepted delivery" so the wording matches the implementation.

Suggested fix

--- "a/docs/webhooks/own-handler.mdx"
+++ "b/docs/webhooks/own-handler.mdx"
@@ -4,7 +4,7 @@
 description: "Receive webhooks in a route in your own app and trigger tasks from it with tasks.trigger()."
 ---
 
-**Trigger.dev has built-in webhook endpoints, and we recommend them for most projects.** They verify each provider's signature, drop duplicate retries, record every delivery, and route events to tasks, agents and waiting runs. See [Webhooks](/webhooks/overview).
+**Trigger.dev has built-in webhook endpoints, and we recommend them for most projects.** They verify each provider's signature, drop duplicate retries, record every accepted delivery, and route events to tasks, agents and waiting runs. See [Webhooks](/webhooks/overview).
 
 If you prefer to handle webhooks yourself, receive them in a route in your own app and trigger runs from there with `tasks.trigger()`, the same way any backend code does.
 
Committable suggestion

IMPORTANT
Review the replacement and indentation, then test before committing.

Suggested change
**Trigger.dev has built-in webhook endpoints, and we recommend them for most projects.** They verify each provider's signature, drop duplicate retries, record every delivery, and route events to tasks, agents and waiting runs. See [Webhooks](/webhooks/overview).
**Trigger.dev has built-in webhook endpoints, and we recommend them for most projects.** They verify each provider's signature, drop duplicate retries, record every accepted delivery, and route events to tasks, agents and waiting runs. See [Webhooks](/webhooks/overview).

}
```

Return quickly: the task runs in the background, so the provider gets its response before the work starts.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Remove the response-before-work guarantee.

The worker can start the task after the trigger is accepted but before this route returns its response. Describe the task as running asynchronously without promising that the response arrives first.


Webhooks have no separate charge on Trigger.dev Cloud. Receiving, verifying, filtering and recording deliveries is included in every plan. The runs a delivery starts or resumes are billed like any other run: a per-run invocation cost plus compute time. See [pricing](https://trigger.dev/pricing).

A delivery that no subscriber's filter matches starts no run, so it adds no run cost. A run already [waiting](/webhooks/waiters) for that webhook still resumes and is billed like any other run. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Account for targeted replays.

A replay with targetId bypasses the subscriber’s filter and can start its task even when the filter does not match. That run can incur a charge. Limit this claim to normal routing, or note the replay exception. (raw.githubusercontent.com)

## Set up Calendly

1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
2. Calendly webhooks are created through the API, on a paid plan. Choose a signing key (for example, the output of `openssl rand -hex 32`), then create the subscription with `POST https://api.calendly.com/webhook_subscriptions`, passing `url` (the webhook URL), `events`, `organization`, `scope` and `signing_key`. If you create the subscription from an OAuth app, Calendly generates the signing key instead.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Remove the blanket paid-plan requirement.

Calendly enabled webhooks on Free plans on November 3, 2026. Events such as invitee.created do not require an upgrade. Only specified event families require a plan with the matching feature. Update this prerequisite so Free-plan users are not incorrectly excluded from setup. (developer.calendly.com)

## Set up DocuSign

1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
2. In DocuSign eSignature Admin, open **Connect > Connect Keys** and choose **Add Secret Key**. Copy the key: DocuSign shows it in full only once. Choose **Set signing secret** on the Trigger.dev endpoint and paste it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Quick win

Use the key that signs x-docusign-signature-1.

If the account already has a Connect key, Add Secret Key creates another key. DocuSign puts that key's signature in another numbered header. The supplied preset reads only x-docusign-signature-1, so storing the new key rejects valid deliveries. Document this restriction and use the securely retained first key, or extend verification to support the additional headers. Do not remove existing keys that other integrations use. (developers.docusign.com)


1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
2. In DocuSign eSignature Admin, open **Connect > Connect Keys** and choose **Add Secret Key**. Copy the key: DocuSign shows it in full only once. Choose **Set signing secret** on the Trigger.dev endpoint and paste it.
3. Add a Connect configuration with the webhook URL, select the events your subscribers need, and tick **Include HMAC Signature**. Without it, DocuSign doesn't sign deliveries and every one is rejected.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Supported by static analysis

Script executed:

rg -n -i -F --glob '*.ts' --glob '*.tsx' --glob '*.mdx' -e 'docusign' -- . || test "$?" -eq 1
echo "---- XML/body parsing in webhook ingress ----"
rg -n -i -F --glob '*.ts' -e 'application/xml' -e 'text/xml' -e 'xml2js' -e 'fast-xml-parser' -- . || test "$?" -eq 1
echo "---- event.event / event field usage ----"
rg -n -F --glob '*.ts' -e 'event.event' -- . || test "$?" -eq 1

Repository: triggerdotdev/trigger.dev

Length of output: 21997


Script executed:

rg -n -F --glob '*.ts' -e 'req.text()' -e 'request.text()' -e 'JSON.parse(' -e 'content-type' -e 'Content-Type' -- apps/webapp/app/routes apps/webapp/app/services internal-packages/webhook-engine/src 2>/dev/null || test "$?" -eq 1
echo "---- webhook receiver route files ----"
rg --files -g '*webhook*' apps/webapp/app internal-packages/webhook-engine/src 2>/dev/null || test "$?" -eq 1

Repository: triggerdotdev/trigger.dev

Length of output: 18507


Script executed:

cat -n internal-packages/webhook-engine/src/engine/verification/derive.ts | sed -n '30,80p'
echo "---- callers of parseEventBody ----"
rg -n -F -e 'parseEventBody(' -- internal-packages/webhook-engine/src apps/webapp/app 2>/dev/null || test "$?" -eq 1

Repository: triggerdotdev/trigger.dev

Length of output: 4658


Require JSON SIM in the DocuSign Connect configuration.

Trigger.dev parses only JSON and form-encoded bodies. An XML Connect delivery passes the HMAC check but produces no parsed event, so event.event filters cannot match it. Specify JSON SIM in the setup step.

Suggested fix

--- "a/docs/webhooks/providers/docusign.mdx"
+++ "b/docs/webhooks/providers/docusign.mdx"
@@ -37,5 +37,5 @@
 
 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
 2. In DocuSign eSignature Admin, open **Connect > Connect Keys** and choose **Add Secret Key**. Copy the key: DocuSign shows it in full only once. Choose **Set signing secret** on the Trigger.dev endpoint and paste it.
-3. Add a Connect configuration with the webhook URL, select the events your subscribers need, and tick **Include HMAC Signature**. Without it, DocuSign doesn't sign deliveries and every one is rejected.
+3. Add a Connect configuration with the webhook URL. Set the data format to **JSON SIM** (`deliveryMode` `SIM`, `eventData.version` `restv2.1`). Trigger.dev cannot parse XML deliveries. Select the events your subscribers need, and tick **Include HMAC Signature**. Without it, DocuSign doesn't sign deliveries and every one is rejected.
 4. Send a test event from DocuSign, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives.
Committable suggestion

IMPORTANT
Review the replacement and indentation, then test before committing.

Suggested change
3. Add a Connect configuration with the webhook URL, select the events your subscribers need, and tick **Include HMAC Signature**. Without it, DocuSign doesn't sign deliveries and every one is rejected.
3. Add a Connect configuration with the webhook URL. Set the data format to **JSON SIM** (`deliveryMode` `SIM`, `eventData.version` `restv2.1`). Trigger.dev cannot parse XML deliveries. Select the events your subscribers need, and tick **Include HMAC Signature**. Without it, DocuSign doesn't sign deliveries and every one is rejected.
Tools

LanguageTool

[grammar] ~40-~40: Ensure spelling is correct
Context: ...t, DocuSign doesn't sign deliveries and every one is rejected. 4. Send a test event from ...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

## Set up Hookdeck

1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
2. In Hookdeck, create a connection whose destination is an HTTP destination with the webhook URL. Keep the destination's authentication on **Hookdeck Signature** (the default); Hookdeck only signs requests with it set.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Security & Privacy · Quick win

Require source authentication for the hosted endpoint path.

If a Hookdeck source has no authentication, anyone with its source URL can submit a fabricated event. Hookdeck signs that event before forwarding it, so checking the Hookdeck signature does not authenticate the original provider. Hookdeck treats source authentication and destination signing as separate controls. (hookdeck.com)

Require the provider's signature verification, or another suitable source authentication method, in this setup. Apply the warning from Line 85 to the hosted endpoint path too.

- **Signature Header**: `x-vapi-signature`
- **Timestamp Header**: leave empty
- **Payload Format**: the request body only, with no timestamp
4. Set the webhook URL as the server URL on your assistant, phone number or Server Configuration, and attach the credential by its `credentialId`. Vapi only sends the credential when the server URL comes from your saved configuration, not from an API request.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Functional Correctness · Quick win

Limit this setup to notification-only events.

If a phone number uses dynamic assistant selection, this step sends assistant-request to the hosted endpoint. Vapi requires an assistant configuration in the HTTP response. The endpoint acknowledges the delivery before the background task supplies any result, so Vapi cannot obtain the assistant. (docs.vapi.ai)

Add a warning before this step. Direct response-required events to /webhooks/own-handler, and reserve this setup for informational events. (docs.vapi.ai)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant