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

# Webhooks and secrets

> Environment-scoped webhook signing secrets and integration credentials

Webhooks and workflow secrets are scoped per environment. The same
endpoint name, the same secret name, and the same workflow config can
hold different values in test and production — and a change to one
environment never leaks into the other.

## Webhook signing secrets

Each environment has its own signing secret:

```text theme={null}
test webhook endpoint        + test signing secret
production webhook endpoint  + production signing secret
```

Implications:

* Rotating the **test** signing secret has no effect on production
  delivery, and vice versa.
* Test event failures appear only in the test webhook log.
* Production event failures appear only in the production webhook log.
* Retries never cross environments.

The dashboard splits webhook settings the same way: a *Test webhook secret*
section and a *Live webhook secret* section. Manage each independently.

## Webhook delivery format

Every delivery includes the environment as a header and inside the JSON
body. Verify the signature using the secret for the matching environment.

```http theme={null}
POST /your/webhook HTTP/1.1
X-Retab-Environment: test
X-Retab-Signature: t=1715000000,v1=...
Content-Type: application/json
```

```json theme={null}
{
  "id": "evt_...",
  "type": "workflow.run.completed",
  "environment": "test",
  "created_at": "2026-05-19T12:00:00Z",
  "data": { }
}
```

Environment is **not** a substitute for signature verification — always
verify the signature with the right secret first, then route on
`environment`.

## Workflow secrets and integration credentials

Workflow configs reference secret names, not values:

```text theme={null}
secret://salesforce_api_key
secret://slack_webhook_url
```

At runtime Retab resolves the reference against the workspace,
environment, and secret name, so the same workflow config can run
against sandbox credentials in test and real credentials in production.

```text theme={null}
test.SALESFORCE_API_KEY       -> Salesforce sandbox
production.SALESFORCE_API_KEY -> Salesforce production

test.SLACK_WEBHOOK_URL        -> internal testing channel
production.SLACK_WEBHOOK_URL  -> production operations channel
```

Set the value of each secret in the dashboard under the environment it
belongs to. If a production run references a secret that does not exist
in production, the run fails fast with a configuration error rather than
falling back to an test value.

## Why this matters

The split is the single biggest reason to use environments:

* Test automations cannot accidentally deliver to a production webhook
  endpoint unless you explicitly configure that endpoint inside test.
* Production runs never use test workflow secrets.
* A misconfigured integration in test can never push to the real
  downstream system.
* Rotating an test secret is safe; production stays exactly as it was.