Multicasting a Webhook

An endpoint can have more than one destination. PayloadRelay can send one incoming request to every attached relay target, such as email, a webhook URL, Slack, Discord, Microsoft Teams, PagerDuty, Telegram, and Google Sheets.

Purpose#

Use this guide to:

• Configure an endpoint with targets of different types.
• Send one webhook to several systems.
• Send a GitHub webhook to several targets.
• Read the delivery outcomes of more than one target.

Before you start#

• Configure two relay targets as a minimum.
• Make sure that the targets are confirmed or active.
• Create an endpoint for the targets.

Procedure#

1. Create the targets#

Create one relay target for each destination. This example uses four targets:

1. Email: ops@example.com. The target must be confirmed.
2. Slack webhook: #github-events channel.
3. Discord webhook: #deployments channel.
4. Webhook URL: https://api.example.com/webhooks/github.

Open Relay targets and create each target. Complete the email target confirmation.

2. Create the multicast endpoint#

1. Open Endpoints and select Create endpoint.
2. Set the accepted method to POST, or to ANY to accept all the methods.
3. Set the payload format to JSON.
4. In Outputs, add all four targets.
5. Save and copy the endpoint URL.

3. Send a payload#

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "event": "push",
    "repository": "acme/web-app",
    "branch": "main",
    "commit": "abc1234",
    "author": "alice",
    "message": "Fix login redirect bug"
  }'

PayloadRelay accepts the request one time and sends it to all four targets:

• Email: ops@example.com receives an email with the payload fields.
• Slack: #github-events receives a formatted message.
• Discord: #deployments receives the payload as message content. If you configure a Discord message template, it receives a formatted embed.
• Webhook: https://api.example.com/webhooks/github receives the complete JSON payload.

4. Use case: GitHub webhook fan-out#

To send the events to several systems, point a GitHub repository webhook at the PayloadRelay endpoint:

1. In GitHub, open the repository. Select Settings, then Webhooks, then Add webhook.
2. Set the Payload URL to your PayloadRelay endpoint URL.
3. Set the Content type to application/json.
4. Enter a strong value in the GitHub Secret field.
5. On the PayloadRelay endpoint, open Security → Inbound authentication. Select HMAC, select the GitHub preset, and enter the same secret. PayloadRelay then examines the GitHub X-Hub-Signature-256 header.
6. Select the events to receive, for example, push, pull_request, or release.
7. Save the two configurations, and send a GitHub test delivery.

Every GitHub event uses one URL and goes to all the configured targets:

GitHub push event
       │
       ▼
  PayloadRelay endpoint
       │
       ├──► Email: ops team gets notified
       ├──► Slack: #github-events channel
       ├──► Discord: #deployments channel
       └──► Webhook: custom application processes the event

The GitHub webhook Secret is an HMAC signing secret. It does not give Basic, Bearer, or API key authentication. For this integration, use the PayloadRelay GitHub HMAC preset.

5. Selective multicast with multiple endpoints#

For more complex routing, create separate endpoints for different event types. You can also add a filter on a destination that uses the X-GitHub-Event request header:

You can thus control which targets receive each event type.

6. Delivery outcomes with multiple targets#

When PayloadRelay sends a payload to more than one target, it records each delivery separately in Request activity:

• The request row can show PENDING while the deliveries continue. It then moves to the final outcome.
• Each destination delivery has its own success, failure, or skipped status.
• If one target fails, for example, when a webhook URL is not available, the other targets still receive the payload.
• The retries apply to each destination. A webhook destination that fails retries with its own configuration. A supported destination that is not a webhook retries automatically, in the limit of the plan.

7. Monitor multicast deliveries#

To read the delivery status of each target:

1. Open Request activity.
2. Find the request by timestamp or by endpoint.
3. The request log shows the inbound outcome and the delivery outcome of each target.

Look for these results:

• ACCEPTED or EMAIL_INGESTION_ACCEPTED when all the tracked deliveries complete successfully. DELIVERY_FAILED means that one necessary delivery or more failed.
• The delivery status of each target (success or failure, with a reason).
• The configured retries for a failed delivery, when that destination has retries available.

Expected result#

• One POST to the endpoint URL starts the deliveries to all the attached targets.
• Each target receives the same payload data.
• Request activity shows one inbound request with a separate delivery entry for each target.
• A failed delivery to one target does not stop the deliveries to the other targets.

Common issues#

• One target does not receive the payload: make sure that the target is attached in Outputs and that it is Available. A platform email target needs a confirmation. A custom SMTP target needs a verification.
• The webhook target fails: make sure that the destination URL is reachable, and that the endpoint destination has the necessary authentication.
• A partial delivery: open Request activity, and read the delivery status and the error reason of each target.
• Duplicate deliveries: make sure that the sending system does not retry while PayloadRelay also retries.

Related guides#

• Relay Targets
• Endpoint Management
• Configure a Slack Integration
• Configure a Discord Integration
• Observability