← Back to documentation

Authentication and Secrets

Configure endpoint and webhook authentication, then change credentials without a long outage.

3 min read

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

Purpose#

Use this guide to:

  • Configure the inbound authentication on an endpoint.
  • Configure the outbound authentication for a webhook destination.
  • Rotate a secret with a short delivery interruption.

Before you start#

  • Make sure that you can edit endpoints.
  • Configure a Webhook URL relay target for outbound delivery.
  • Use a secure place for the secrets, such as a vault or a password manager.

Procedure#

1. Configure inbound authentication#

In endpoint Security:

  • None
  • Basic with a username and a password. A username cannot contain : or control characters.
  • Bearer token
  • API key header (a header name and a secret value)
  • HMAC (a provider preset or a custom signature verification)

Best practices:

  • Use one credential set for each endpoint.
  • Use a different secret for each environment.

2. Configure additional inbound protection#

Optional controls:

  • Required request headers with a maximum of 20 exact-value rules. A name is a case-insensitive HTTP header token. A value is case-sensitive.
  • Human verification through Turnstile or reCAPTCHA for a JSON, form, or XML payload

Use the required headers for a service-to-service trust boundary. Use the inbound authentication types for Authorization or API key authentication.

3. Configure outbound webhook authentication#

For each Webhook URL destination in the Outputs tab:

  • Select an authentication type: None, Basic, Bearer, or API key. A Basic username cannot contain : or control characters.
  • Keep Enforce HTTPS enabled. Disable it only if the destination uses plain HTTP intentionally.
  • If the destination needs custom headers, add them.

PayloadRelay applies these rules:

  • An API key header name cannot use a restricted HTTP header such as Authorization, Host, Cookie, or a hop-by-hop or protocol header.
  • Each custom header name must be unique and valid.
  • A custom header cannot conflict with an authentication header, a restricted HTTP header, or an outbound HMAC signing, timestamp, or previous-signature header.
  • PayloadRelay blocks a private-network target and a localhost target.

4. Rotate secrets safely#

Use this sequence:

  1. Prepare the destination to accept the new secret.
  2. Update the endpoint security configuration or the webhook destination secret in PayloadRelay.
  3. Send representative traffic through the saved endpoint. Make sure that the delivery succeeds. The Test action on the target examines reachability only. It does not apply the authentication of the destination.
  4. Remove the old secret from the destination.

To rotate the endpoint URL, use Regenerate URL. Do this only if a rotation is necessary. Then update all the senders immediately.

Expected result#

  • An unauthorized request fails with AUTH_FAILED.
  • The destination systems accept the relayed requests after the rotation.
  • There is no long outage during a credential change.

Common issues and fixes#

  • A Basic, Bearer, or API key mismatch: make sure that the configured authentication type matches the destination.
  • An unexpected header authentication failure: make sure that the header name and the value match exactly.
  • A blocked non-HTTPS destination: use an HTTPS URL, or disable Enforce HTTPS on that endpoint destination. PayloadRelay still rejects an invalid TLS certificate. Correct the certificate chain.
← Back to documentation