Skip to content

docs: restructure the webhooks docs with a page per provider - #5124

Merged
jackbridger merged 37 commits into
mainfrom
docs/webhooks-restructure
Nov 17, 2026
Merged

jackbridger merged 37 commits into
mainfrom
docs/webhooks-restructure

Conversation

@jackbridger

Copy link
Copy Markdown
Collaborator

Summary

Restructures the webhooks docs so each page does one job, and adds a setup page for every built-in provider.

  • Every built-in provider gets its own page under Webhooks > Providers: the source function, how verification works, which credential it uses, and the steps to register the URL and set the secret in that provider. Setup steps were checked against each provider's current webhook docs.
  • The overview is shorter and routes to new pages: a quick start, how it works, pricing and limits, custom providers, signing secrets, webhook tasks, and using your own handler. The quick start was run end to end against a fresh project.
  • "Sources" is now "Verification", with "provider" meaning the service and "source" meaning the source value in code.
  • The Stripe and Hookdeck example guides are replaced by their provider pages. The Next.js and Remix guides are renamed "Custom webhook handler with ..." and point to the built-in endpoints first.
  • Slack agents, Linear agents, channels and channel human-in-the-loop move into a Channels group in the Agents section. Their URLs are unchanged.
  • Zoom, Notion, Brex and Intercom have no provider page for now, because setup can't be completed for them yet.

Every removed or renamed URL redirects to its new home.

The custom HMAC additionalSignatureHeaders paragraph from #5045 is included on the Custom providers page, since that PR edits the old sources page.

- 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.
@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 9c8e2ab

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

@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The documentation navigation now groups webhook content by setup, providers, event handling, and deliveries and limits. New pages cover webhook setup, processing, verification, credentials, custom providers, application-owned handlers, pricing, and provider-specific instructions. The changes also revise webhook behavior references and framework guides, remove older webhook guides, update related cards, and add redirects for former URLs.

Merge Risk: Low · up to 9c8e2

This documentation reorganization is safe to merge. The Attio, DocuSign and Sentry setup steps match how those providers work. A known mismatch in the product's secret-provisioning setting for those providers is being tracked separately and has a simple workaround.

Pre-merge checks: Passed 3 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Description check Inconclusive The description follows the template's required structure. It has a Summary section that explains the restructuring, the provider pages, the terminology change, the removed guides, and the redirects. … Add the template sections that are missing: a Closes # line (or state that no issue exists), the checklist with each item checked or explained, a Testing section that lists the steps used to verify the quick start and the provider se…
Passed Passed checks: 3 passed

Check name Status Explanation
Title check Passed The title names the main change: the webhooks docs are restructured with a dedicated page for each built-in provider. The PR summary and objectives confirm this is the primary change. The title is spe…
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 names the main change: the webhooks docs are restructured with a dedicated page for each built-in provider. The PR summary and objectives confirm this is the primary change. The title is specific and concise, and it follows the docs: prefix convention.

Full details: Description check

Explanation

The description follows the template's required structure. It has a Summary section that explains the restructuring, the provider pages, the terminology change, the removed guides, and the redirects. It does not include the template's Closes #<issue> line, the checklist, the Testing section, the Changelog section, or the Screenshots section. The author did state that the quick start was tested end to end, but that is not a full Testing section. Those template items are missing, so the description is only partly complete.

Resolution

Add the template sections that are missing: a Closes #<issue> line (or state that no issue exists), the checklist with each item checked or explained, a Testing section that lists the steps used to verify the quick start and the provider setup steps, a Changelog entry, and a Screenshots section (or a note that none apply to these docs changes).

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

Recent 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: 164ec5f8-317b-4eac-832c-2d778e2d8ae7
Commits

Reviewing files that changed from the base of the PR and between 9f1576d and 9c8e2ab.

Files selected for processing: 3

  • docs/docs.json
  • docs/webhooks/sources.mdx
  • docs/webhooks/verification.mdx
Files with no reviewable changes: 1

  • docs/webhooks/sources.mdx

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

Recent review details

Context from checks skipped due to timeout: 2

  • GitHub Check: Analyze (javascript-typescript)
  • GitHub Check: Build and publish previews
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/webhooks/verification.mdx
Source excerpt: Use Mintlify MDX format.

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

Files:

  • docs/docs.json
  • docs/webhooks/verification.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/webhooks/verification.mdx
Learnings: 2

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-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/verification.mdx
Additional comments: 1

docs/docs.json: 1

151-159: LGTM!

Also applies to: 197-271, 632-633, 890-940

devin-ai-integration[bot]

This comment was marked as resolved.

devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

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.
coderabbitai[bot]

This comment was marked as resolved.

@devin-ai-integration devin-ai-integration 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.

Devin Review found 0 new potential issues.

Devin Review

Send the wrapped body as JSON, accept any payload type, and require
authentication on the Hookdeck source.
@jackbridger
jackbridger added this pull request to the merge queue Nov 13, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 13, 2026
…ture

# Conflicts:
#	docs/webhooks/sources.mdx
@pkg-pr-new

pkg-pr-new Bot commented Nov 17, 2026

Copy link
Copy Markdown

Open in StackBlitz

@trigger.dev/build

npm i https://pkg.pr.new/@trigger.dev/build@9c8e2ab

trigger.dev

npm i https://pkg.pr.new/trigger.dev@9c8e2ab

@trigger.dev/convex

npm i https://pkg.pr.new/@trigger.dev/convex@9c8e2ab

@trigger.dev/core

npm i https://pkg.pr.new/@trigger.dev/core@9c8e2ab

@trigger.dev/linear

npm i https://pkg.pr.new/@trigger.dev/linear@9c8e2ab

@trigger.dev/python

npm i https://pkg.pr.new/@trigger.dev/python@9c8e2ab

@trigger.dev/react-hooks

npm i https://pkg.pr.new/@trigger.dev/react-hooks@9c8e2ab

@trigger.dev/redis-worker

npm i https://pkg.pr.new/@trigger.dev/redis-worker@9c8e2ab

@trigger.dev/rsc

npm i https://pkg.pr.new/@trigger.dev/rsc@9c8e2ab

@trigger.dev/schema-to-json

npm i https://pkg.pr.new/@trigger.dev/schema-to-json@9c8e2ab

@trigger.dev/slack

npm i https://pkg.pr.new/@trigger.dev/slack@9c8e2ab

@trigger.dev/sdk

npm i https://pkg.pr.new/@trigger.dev/sdk@9c8e2ab

commit: 9c8e2ab

@jackbridger
jackbridger added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 110f6d8 Nov 17, 2026
29 checks passed
@jackbridger
jackbridger deleted the docs/webhooks-restructure branch November 17, 2026 10:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants