← Back to documentation

Relay Targets

Manage email, webhook, Slack, Discord, Microsoft Teams, PagerDuty, Telegram, and Google Sheets targets.

8 min read

A relay target is a saved connection to a system that receives the data. A destination attaches a relay target to an endpoint, and it stores the delivery configuration for that endpoint.

The target list uses Available for a target that you can attach to a destination. A platform email target becomes available after the confirmation. A custom SMTP email target becomes available after Verify connection succeeds. A Google Sheets target becomes available after PayloadRelay makes sure that the connected Google account can edit the selected spreadsheet. The other target types are available immediately. Available does not mean that PayloadRelay examined the reachability of the receiver, unless this guide gives a different statement.

Purpose#

Use this guide to:

  • Create and edit targets.
  • Know which values belong to a target and which values belong to a destination.
  • Connect a Google Sheets file and select a sheet.
  • Complete the email confirmation.
  • Send test deliveries.
  • Remove the targets that you do not use.

Before you start#

  • A signed-in account.
  • Valid destination details for the target type: an email address, a webhook URL, a Slack, Discord, or Teams webhook URL, a PagerDuty integration key, the Telegram bot credentials and chat credentials, or Google Sheets access.
  • A Google Sheets target needs a Google account and a spreadsheet that you can edit.

Procedure#

1. Create a target#

  1. Open Relay targets.
  2. Select Add target.
  3. Select the type:
  • Email
  • Webhook URL
  • Slack webhook
  • Discord webhook
  • Microsoft Teams
  • PagerDuty
  • Telegram
  • Google Sheets
  1. Enter the destination details for that type. The name and the description are optional.
  2. Save.

2. Configure webhook targets (Webhook URL type)#

You configure the webhook authentication, the custom headers, the body customization, and the header forwarding for each endpoint on the Outputs tab of the endpoint editor. PayloadRelay does not store them on the relay target. See Endpoint Management: Configure outputs.

The relay target values for the Webhook URL type:

  • The URL must use http or https. If the URL gives a port, the port must be from 1 to 65535. The URL must not point to localhost or to a private-network range. PayloadRelay rejects a URL fragment (#...) and a username or a password in the URL. Configure the authentication on the destination.
  • PayloadRelay stores the Webhook, Slack, Discord, and Microsoft Teams URLs encrypted, and it shows a masked value after you save. To keep the existing URL when you edit one of these targets, leave the URL field blank.
  • The name and the description are optional.

3. Configure Google Sheets targets#

  1. Select Google Sheets as the target type.
  2. When the page asks you, connect Google.
  3. Select one spreadsheet file.
  4. Select an existing sheet name, or enter a new name.

Behavior:

  • When you save, PayloadRelay makes sure that the connected Google account can edit the selected spreadsheet. PayloadRelay rejects a read-only spreadsheet before the first delivery. A rejected save does not use the Google connection. Correct the sharing in Google Sheets, then save again. You do not connect Google again.
  • If Google applies a temporary rate limit during the save, the page shows a "try again in a moment" error. Do the save again. You can keep the same spreadsheet.
  • PayloadRelay does this permission test each time that you save a Google Sheets target with a new spreadsheet. The limit is 20 saves in 5 minutes for each user.
  • If the sheet name does not exist, PayloadRelay creates it at the first delivery.
  • In an organization, the interface gives a warning that other people in the organization can edit the relay target.
  • During an edit, the owner of the target can open the picker again with the saved Google connection. A different organization member can edit the target, but must connect Google again before a change or a refresh of the sheet selection.

How PayloadRelay writes the rows and columns

  • Row 1 is the header row. PayloadRelay reads it again before each delivery. PayloadRelay uses the columns that you add, remove, rename, or move manually for the next row.
  • A payload field with no column that matches adds a new column to row 1. PayloadRelay never writes an existing column again, and it never moves an existing column.
  • PayloadRelay writes the values as plain text. PayloadRelay stores a value that starts with =, +, or @ as a literal value, and the spreadsheet does not evaluate it as a formula. The numbers and the dates arrive as text. If you need typed values, convert them in the sheet.
  • PayloadRelay flattens the nested JSON with dots (customer.email) and the arrays by index (items.0). If two fields use the same column, PayloadRelay adds a suffix to the later field. This applies to a literal "a.b" key beside a nested {"a":{"b":…}}, and to Email beside email.
  • PayloadRelay cuts a cell value that is longer than 49,500 characters, and it adds … at the end. Activity then records the delivery with a warning that gives the number of values that changed.
  • PayloadRelay rejects a payload that makes more than 5,000 columns for this destination, and Activity records a failed delivery. PayloadRelay writes nothing to the spreadsheet. The other destinations on the endpoint continue. If the payload has many fields, use save selected fields to select the columns.

4. Complete email target confirmation#

An email target starts as Pending.

  1. Open the confirmation link.
  2. Read the email address on the confirmation page. The link opens the page and does not complete the confirmation.
  3. To complete the confirmation, select Confirm relay target.
  4. Make sure that the status becomes Confirmed.

Resend confirmation is available for a pending platform email target. A custom SMTP email target uses Verify connection. You can select that target after Verify connection succeeds.

For each address, PayloadRelay sends one confirmation email in two minutes, and three in one hour. Your organization also has a limit of 30 in one hour, and the invitation emails use the same limit. PayloadRelay refuses a create, an edit, or a resend that is more than a limit, and it changes nothing. If PayloadRelay refuses a request, wait and send it again.

5. Edit or delete targets#

  • You cannot change the type after you create the target.
  • To keep the stored values during an edit, leave the secret fields blank.
  • The deletion fails while a destination uses the target.

6. Send test deliveries#

Use Send test in the target list. For a Webhook URL target, the action is named Test reachability, because it examines only the target URL, and not the complete delivery configuration of a destination.

The behavior for each type:

  • Email: a platform email target needs the Confirmed status. A custom SMTP email target needs a successful Verify connection action.
  • Slack and Discord: PayloadRelay sends a test message.
  • Microsoft Teams: PayloadRelay sends a test card.
  • PagerDuty: PayloadRelay sends a trigger event and then a resolve event, and the test leaves no open incident.
  • Telegram: PayloadRelay sends a test message to the configured chat.
  • Webhook: select POST, PUT, or PATCH, and a payload format. Select if the test includes a body.
  • Google Sheets: PayloadRelay sends a test row to the configured spreadsheet and sheet.

Webhook test rules:

  • The reachability test goes directly to the target URL with no authentication.
  • The test does not use the destination authentication, the custom headers, the HMAC signing, the HTTPS enforcement, the body customization, the header forwarding, the retries, the failover, the routing filters, and the response forwarding. This is intentional, because destinations with a different configuration can use one relay target.
  • A successful reachability test does not prove that a configured destination succeeds. Send a representative request through the saved endpoint. This request uses the complete path.
  • The test outcomes appear in Activity as Test accepted (TEST_ACCEPTED), Test Rejected (TEST_REJECTED), or Test Rate Limited (TEST_RATE_LIMITED). Expand the row for the delivery result of each target.
  • PayloadRelay can rate-limit a test delivery temporarily. If this occurs, wait for the retry window.

Expected result#

  • The target appears with the expected type and availability status.
  • You can select an available target in an endpoint destination. A platform email target needs the confirmation, and a custom SMTP email target needs the connection test.
  • You can create more than one PagerDuty target for different services or integration keys, and select each one independently in an endpoint destination.
  • Activity shows the test deliveries.

Common issues and fixes#

  • An invalid target URL: examine the protocol and the host format. Do not use a private host.
  • PayloadRelay blocks an email target in a destination: complete the confirmation for a platform email target, or select Verify connection for a custom SMTP target.
  • The Google Sheets picker is not available: connect Google again, and make sure that the account has access to the spreadsheet.
  • Google Sheets delivery errors: make sure that the connected Google account can still edit the spreadsheet. Make sure that the sheet name is correct.
  • You cannot select the PagerDuty target that you expect: create one target for each PagerDuty service or integration. Select the target by name in the endpoint destination.
  • PayloadRelay rejects the Telegram delivery: make sure that the bot token and the chat ID are correct. Make sure that the bot can access the chat or the channel.
  • PayloadRelay rate-limits the test: wait for the Retry-After window.
  • PayloadRelay rejects the webhook reachability test: make sure that the URL accepts the selected method and payload. This target-level test does not use the authentication of a destination. If the destination needs those credentials, send a request through the saved endpoint.
← Back to documentation