> ## Documentation Index
> Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook signing secrets

> Set, generate and rotate the credential an endpoint verifies deliveries with, from the dashboard, the CLI, the MCP server or the REST API.

**Each endpoint verifies deliveries with one credential: a signing secret, or a public key for providers that sign with a key pair.** Every delivery is rejected until the credential is set.

## Set the credential

| Action | Use it when |
| - | - |
| **Set signing secret** | The provider issues the secret, as Stripe and Svix do. |
| **Generate secret** | The provider accepts a secret you choose, as GitHub does. Trigger.dev shows it once. |
| **Set public key** | The provider signs with a key pair, as Discord does. |

Each [provider page](https://trigger.dev/docs/webhooks/providers.md) says which one that provider needs.

## Rotate a credential

Choose **Rotate signing secret** to replace a provider-supplied secret. For a secret you generate, choose **Regenerate secret**, copy the new value, and update the provider's configuration. Use **Rotate public key** when replacing an asymmetric provider's key.

Both dialogs ask how long to keep accepting the old secret: **Stop immediately**, 1 hour, 24 hours (the default) or 7 days. Until then, deliveries signed with either secret verify, so you can update the provider without failing any. Choose **Stop immediately** if the old secret leaked.

Through the MCP tools or the REST API, pass `previousSecretTtlSeconds` (at most 604800, 7 days). The response's `previousSecretExpiresAt` says when the old secret stops working. Without it, the old secret stops working straight away:

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/github/rotate-secret" \
  -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"previousSecretTtlSeconds": 3600}'
```

> [!WARNING]
>
> Trigger.dev stores credentials encrypted and doesn't display saved values. Copy a generated secret
> before closing the dialog.

## Store secrets from the CLI

The [CLI webhooks commands](https://trigger.dev/docs/cli-webhooks-commands.md) store a secret without printing it. Use them with AI agents that can run shell commands: a secret passed to `set_webhook_secret`, or returned by `generate_webhook_secret`, becomes part of the agent's conversation, and the MCP tool descriptions point agents to the CLI instead.

```bash theme={"theme":"css-variables"}
# Store a secret the provider issued, from an env file or a pipe
npx trigger.dev@latest webhooks set-secret stripe --env prod --from-env STRIPE_WEBHOOK_SECRET

# Generate one and save it to .env.local for the agent to pass to the provider by name
npx trigger.dev@latest webhooks generate-secret github --env prod --to-env GITHUB_WEBHOOK_SECRET
```

## MCP tools

The Trigger.dev MCP server (`npx trigger.dev@latest install-mcp`) has these webhook tools:

| Tool | What it does |
| - | - |
| `list_webhook_endpoints` | Lists the environment's endpoints, with their URL and whether a secret is set. |
| `get_webhook_endpoint_details` | Reads one endpoint: URL, subscribers and their filters, secret state, and the setup prompt. |
| `generate_webhook_secret` | Generates a signing secret and returns it once, for providers where you choose the secret. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
| `set_webhook_secret` | Stores a secret the provider issued. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |

## REST API

The same operations are available on the REST API with the environment's secret key:

| Request | What it does |
| - | - |
| [`GET /api/v1/webhooks/endpoints`](https://trigger.dev/docs/management/webhooks/list-endpoints) | Lists the environment's endpoints, with their URL and whether a secret is set. |
| [`GET /api/v1/webhooks/endpoints/{endpointId}`](https://trigger.dev/docs/management/webhooks/retrieve-endpoint) | Reads the endpoint, including `subscribers` and `setupPrompt`. |
| [`POST /api/v1/webhooks/endpoints/{endpointId}/rotate-secret`](https://trigger.dev/docs/management/webhooks/generate-secret) | Generates a secret and returns it once. |
| [`PUT /api/v1/webhooks/endpoints/{endpointId}/secret`](https://trigger.dev/docs/management/webhooks/set-secret) | Stores a secret, sent as `{ "secret": "..." }`. |

`endpointId` is the endpoint's declared id (the `id` passed to `webhooks.endpoint.define`) or its `wh_` id, shown on its page and returned by `list_webhook_endpoints`:

```bash theme={"theme":"css-variables"}
curl -X PUT "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/secret" \
  -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret": "whsec_..."}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.