Adding Authentication When Forwarding a Webhook

PayloadRelay supports authentication on the two sides of a relay. Inbound authentication controls who can send to the endpoint. Outbound authentication controls how PayloadRelay authenticates with the destination. This guide shows how to configure the two sides.

Purpose#

Use this guide to:

• Protect an endpoint with inbound authentication.
• Configure outbound authentication on a webhook destination.
• Build an authenticated relay between two services.
• Select an authentication type for your use case.

Before you start#

• Make sure that you can edit endpoints and create or edit relay targets.
• Get the credentials of the sending service for the inbound authentication.
• Get the credentials of the destination service for the outbound authentication.

Procedure#

1. Understand the two authentication layers#

Sending Service ──auth──► PayloadRelay Endpoint ──auth──► Destination Service
                 (inbound)                        (outbound)

• Inbound authentication makes sure that the sender can use the endpoint.
• Outbound authentication authenticates PayloadRelay with the destination.

Each layer is independent. You can use inbound authentication, outbound authentication, or the two together.

2. Configure inbound authentication#

Open the endpoint in Endpoints. Select Security, then select an authentication type:

Use this type for service-to-service communication and an API integration.

1. Select Bearer token as the authentication type.
2. Enter a strong token value, for example, a value from openssl rand -hex 32.
3. Save.

The sender must put the token in every request:

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{"event": "order.created", "order_id": "12345"}'

If the destination needs a custom header name, use this type.

1. Select API key header as the authentication type.
2. Set the header name, for example, X-Api-Key.
3. Enter the key value.
4. Save.

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "X-Api-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"event": "order.created", "order_id": "12345"}'

Use this type for a simple integration and a tool that supports HTTP Basic authentication.

1. Select Basic as the authentication type.
2. Enter the username and the password.
3. Save.

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"event": "order.created", "order_id": "12345"}'

A request with no valid credentials receives a 401 response. It appears as Auth Failed (AUTH_FAILED) in Activity.

3. Configure outbound authentication#

Open the endpoint in Endpoints. Select Outputs, then configure the authentication on the destination that uses the webhook target:

Bearer token (outbound)

1. Edit the endpoint and select the Outputs tab.
2. Expand the configuration of the webhook destination.
3. Select Bearer as the authentication type.
4. Enter the Bearer token that the destination expects.
5. Save.

PayloadRelay adds Authorization: Bearer <token> to every forwarded request.

API key header (outbound)

1. Edit the endpoint, and expand the webhook destination configuration in Outputs.
2. Select API key as the authentication type.
3. Set the header name that the destination expects, for example, X-Api-Key.
4. Enter the key value.
5. Save.

Basic authentication (outbound)

1. Edit the endpoint, and expand the webhook destination configuration in Outputs.
2. Select Basic as the authentication type.
3. Enter the username and the password that the destination expects.
4. Save.

Custom headers (outbound)

For a destination that needs more headers than the authentication headers:

1. Edit the endpoint, and expand the webhook destination configuration in Outputs.
2. Add a maximum of 25 custom headers. Mark a credential-like header as sensitive. PayloadRelay encrypts these values, and it does not show them after you save. A header value supports a template variable such as {{originating_ip}} and {{uuid}}.
3. Save.

For example, a destination needs an API key and a tenant ID header:

• Auth type: API key with header X-Api-Key
• Custom header: X-Tenant-Id: acme-corp

Header forwarding

You can forward a header from the incoming request to the webhook target:

• Forward all incoming headers: PayloadRelay forwards the permitted headers from the incoming request. PayloadRelay always removes the restricted headers and the endpoint-specific credential headers.
• Forward specific headers: PayloadRelay forwards the header names that you give. If a header is not in the incoming request, PayloadRelay ignores it.

A custom header has priority over a forwarded header with the same name.

PayloadRelay always removes these restricted headers. They are connection-specific, or PayloadRelay sets them for the outbound request, or they are security-sensitive:

Host, Connection, Content-Length, Content-Type, Transfer-Encoding, Upgrade, Proxy-Authorization, Proxy-Connection, TE, Trailer, Expect, Keep-Alive, HTTP2-Settings, Authorization, Cookie, Set-Cookie, X-PayloadRelay-Forward-Chain, X-PayloadRelay-Delivery-Id, X-PayloadRelay-Event-Id, X-PayloadRelay-Attempt

PayloadRelay also removes the endpoint required-header names, the inbound API key header, the inbound HMAC signature header, and the Slack timestamp header that the Slack HMAC preset uses. A template cannot use these dynamic credential headers and validation headers. The specific-header list cannot send them. If the destination needs its own credential, configure separate outbound authentication or a sensitive custom header on the destination.

4. HTTPS enforcement#

For an outbound webhook destination, enable Enforce HTTPS to reject a target URL that does not use HTTPS. An HTTPS connection always uses the normal TLS certificate validation. If you disable this control, PayloadRelay still rejects an invalid certificate.

5. End-to-end example: secure webhook relay#

In this example, Service A sends order events to Service B through PayloadRelay. The two sides use authentication.

Step 1: Create the webhook target for Service B

1. Open Relay targets, select Add target, then select Webhook URL.
2. Enter the URL of Service B: https://api.service-b.com/webhooks/orders
3. Save.

Step 2: Create the endpoint

1. Open Endpoints and select Create endpoint.
2. Set the method to POST and the payload format to JSON.
3. In Security, set the authentication type to Bearer token with a token for Service A.
4. In Outputs, attach the Service B webhook target.
5. Configure the outbound authentication with the type Bearer and the token of Service B.
6. Enable Enforce HTTPS.
7. Save the endpoint. Give the endpoint URL and the token to the Service A team.

Step 3: Service A sends events

# Service A sends to PayloadRelay
curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Authorization: Bearer service-a-token" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.created",
    "order_id": "ORD-98765",
    "customer": "[email protected]",
    "total": 149.99,
    "currency": "USD"
  }'

What happens:

1. PayloadRelay examines the Bearer token of Service A for the inbound authentication.
2. PayloadRelay accepts the request for delivery.
3. PayloadRelay sends the payload to https://api.service-b.com/webhooks/orders with the Bearer token of Service B for the outbound authentication.
4. Activity records the inbound acceptance and the outbound delivery.

6. Compare authentication types#

7. Rotate credentials#

Use this procedure to change the authentication credentials:

1. Update the destination to accept the old credentials and the new credentials.
2. Update the PayloadRelay endpoint security configuration or the webhook destination with the new credential.
3. Send a representative request through the saved endpoint. Make sure that the destination receives it.
4. Remove the old credential from the destination.

This sequence prevents a delivery failure during the change.

Expected result#

• A request with no authentication returns 401 with AUTH_FAILED.
• A request with valid authentication returns 202 Accepted after PayloadRelay accepts the event. A temporary failure can return 503 with Retry-After. Wait for the given time, then send the request again with the same event key. For the destination delivery outcome, follow Activity.
• A forwarded request contains the configured outbound authentication headers.
• An inbound authentication failure appears as AUTH_FAILED. An outbound credential problem appears in the destination delivery outcome and the error details.

Common issues#

• AUTH_FAILED on the inbound side: make sure that the authentication type and the credential values agree with the endpoint configuration.
• An outbound delivery failure: make sure that the webhook destination uses the authentication type and the credentials that the destination needs.
• PayloadRelay blocks a target that does not use HTTPS: use HTTPS, or disable Enforce HTTPS for that destination. With this control disabled, PayloadRelay still rejects a self-signed certificate and a different invalid TLS certificate. Correct the certificate.
• A custom header conflict: a custom header cannot use the same name as an authentication header. For example, you cannot add a custom Authorization header when Bearer authentication is enabled.

Related guides#

• Authentication and Secrets
• Relay Targets
• Endpoint Management
• Multicasting a Webhook