← Back to documentation

Authentication and Secrets

Configure endpoint and webhook authentication safely, including rotation and verification patterns.

9 min read

Use this guide to secure inbound endpoint traffic and outbound webhook deliveries.

Purpose

This guide helps you:

  • Configure inbound auth on endpoints.
  • Configure outbound auth for webhook relay targets.
  • Rotate secrets with minimal delivery disruption.

Prerequisites and permissions

  • Endpoint edit access.
  • Relay target edit access (for webhook targets).
  • Team secret management process (vault/password manager).

Step-by-step workflow

1. Configure inbound endpoint auth

In endpoint Security:

  • None
  • Basic (username + password)
  • Bearer token
  • API key header (header name + secret value)

Best practices:

  • Use one credential set per endpoint.
  • Avoid shared secrets across environments.

2. Configure inbound hardening checks

Optional controls:

  • Required request headers (exact value checks)
  • Human verification via Turnstile/reCAPTCHA for JSON/Form payloads

Use required headers for service-to-service trust boundaries.

3. Configure outbound webhook auth

For Webhook URL targets:

  • Choose auth type (None, Basic, Bearer, API key)
  • Set Require valid SSL certificate
  • Add custom headers when needed

Rules enforced by the system:

  • Custom header names must be unique and valid.
  • Custom headers cannot conflict with auth headers.
  • Private-network/localhost targets are blocked.

4. Rotate secrets safely

Recommended sequence:

  1. Prepare destination to accept new secret.
  2. Update endpoint or target secret in PayloadRelay.
  3. Validate with controlled traffic / target tests.
  4. Remove old secret from destination.

For endpoint URL rotation, use Regenerate URL only when required and update all senders immediately.

Expected result and verification checks

  • Unauthorized requests fail with AUTH_FAILED.
  • Destination systems accept relayed requests after rotation.
  • No prolonged outage during credential changes.

Common issues and fixes

  • Basic/Bearer/API key mismatch: verify configured auth type matches destination expectation.
  • Unexpected header auth failures: confirm exact header name/value.
  • SSL enforcement failures: fix destination certificate chain or disable enforcement temporarily.

Related guides

← Back to documentation