Repository navigation
docs(webhooks): document additionalSignatureHeaders for custom HMAC sources - #5045
mintlify[bot] wants to merge 3 commits into
Conversation
|
|
Important Review skippedBot user detected. To trigger a single review, invoke the ⚙️ Run configuration
You can disable this status message by setting the Use the checkbox below for a quick retry:
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. Comment |
|
|
||
| The rotate and regenerate dialogs include **Keep accepting the old signing secret for** (or the old public key). Trigger.dev keeps verifying deliveries signed with the old credential until that time passes, so you can update the provider without failing deliveries. Choose **1 hour**, **24 hours** (the default) or **7 days**. Choose **Stop immediately** if the old credential leaked. | ||
|
|
||
| Over the API, pass `previousSecretTtlSeconds` (up to `604800`, 7 days) to [generate a secret](/management/webhooks/generate-secret) or [set a secret](/management/webhooks/set-secret). The response includes `previousSecretExpiresAt`. Without `previousSecretTtlSeconds`, the old secret stops verifying immediately. |
There was a problem hiding this comment.
| }); | ||
| ``` | ||
|
|
||
| To accept a signature from more than one header, list the extra headers in `additionalSignatureHeaders` (up to 4). Trigger.dev parses them like `signatureHeader` and accepts a match in any of them. This keeps deliveries verifying when a provider sends a second signature during a secret rotation, such as Hookdeck's `x-hookdeck-signature-2`. `signatureHeader` is still required. |
There was a problem hiding this comment.
🔍 Primary signature header remains mandatory per request
An additional header alone cannot verify a delivery: prepareSignedVerification rejects missing or unparseable primary signatures first. Clarifying this constraint helps users configure providers that switch headers during rotation.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Devin Review found 2 new potential issues.
⚠️ 1 issue in files not directly in the diff
⚠️ Generated clients lose rotation grace period
When clients use this schema, previousSecretTtlSeconds disappears from both secret-rotation requests. The rotate-secret handler still accepts it, so generated clients cannot request the supported grace period.
| }); | ||
| ``` | ||
|
|
||
| To accept a signature from more than one header, list the extra headers in `additionalSignatureHeaders` (up to 4). Trigger.dev parses each one like `signatureHeader` and accepts a match in any of them. Use this when a provider sends a second signature, for example one signed with the previous secret during a rotation. `signatureHeader` is still required. The built-in [`hookdeck()`](#hookdeck) source already checks `X-Hookdeck-Signature-2` this way. |
There was a problem hiding this comment.
🔍 Hookdeck example points to nonexistent source
The #hookdeck anchor has no matching section, and webhookSources exposes no hookdeck() preset. Readers cannot follow this example or configure the claimed built-in source.
Was this helpful? React with 👍 or 👎 to provide feedback.
@trigger.dev/build
trigger.dev
@trigger.dev/core
@trigger.dev/linear
@trigger.dev/python
@trigger.dev/react-hooks
@trigger.dev/redis-worker
@trigger.dev/rsc
@trigger.dev/schema-to-json
@trigger.dev/slack
@trigger.dev/sdk
commit: |
…dotdev#5124) ## 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 [triggerdotdev#5045](triggerdotdev#5045) is included on the Custom providers page, since that PR edits the old sources page.
Summary
The custom providers section now explains
additionalSignatureHeaders. You can use it to accept an HMAC signature from up to 4 extra headers, for example when a provider sends a second signature signed with the previous secret during a rotation.Based on feat(webapp,webhook-engine): keep the old webhook signing secret valid during rotation, which added the option to HMAC verifier configs. The paragraph also points to the built-in
hookdeck()source from feat(core,sdk): webhooks.hookdeck() source, which already handlesX-Hookdeck-Signature-2.The rotation grace period edits to the connect page and OpenAPI spec are dropped. Eric already covered them in previousSecretTtlSeconds in the API client and MCP tools.
Docs only. Mark ready for review to merge.