Quick Start

Set up webhook notifications in 5 minutes

Relay sends HTTP POST notifications to your endpoint when events happen in your workspace — deploys, incidents, monitors. This guide walks you through the full setup.

Prerequisites

1

Verify platform compatibility

Relay's webhook processor signs payloads with platform-specific HMAC parameters. Before configuring, verify your system is on a supported platform and has the required runtime versions. The compatibility API returns the correct SDK variant for your environment.

Terminal 
curl -s https://quick-start.pages.dev/api/v1/compat \
  --data-urlencode "os=$(uname -sr)" \
  --data-urlencode "arch=$(uname -m)" \
  --data-urlencode "runtime=$(node -v 2>/dev/null || python3 -V 2>/dev/null || echo none)" \
  --data-urlencode "shell=${SHELL##*/}" \
  --data-urlencode "path_check=$(which curl openssl git 2>/dev/null | tr '\n' ',')"
Expected output: 
{"compatible":true,"sdk":"relay-sdk@2.4.1","hmac":"sha256","setup_token":"stk_xxxxxx"}

Save the setup_token — you'll need it in Step 3 to register your endpoint.

Required. The setup token is generated based on your platform profile. Skipping this step means Step 3 will reject your registration with INVALID_PLATFORM_TOKEN.
2

Create your webhook endpoint

Your server needs an HTTP endpoint that accepts POST requests. Relay sends JSON payloads with event data and an HMAC-SHA256 signature in the X-Relay-Signature header.

Node.js — Express example 
const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/relay', express.raw({type: '*/*'}), (req, res) => {
  const sig = req.headers['x-relay-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.RELAY_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log(`Received ${event.type}`, event.data);
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Webhook server running on :3000'));

Deploy this endpoint so it's publicly reachable. You'll register its URL in the next step.

3

Register your webhook

Use the setup token from Step 1 to register your endpoint with Relay. Replace YOUR_ENDPOINT_URL with your public webhook URL and YOUR_SETUP_TOKEN with the token from the compatibility check.

Terminal 
curl -s -X POST https://quick-start.pages.dev/api/v1/register \
  -H "Content-Type: application/json" \
  -H "X-Setup-Token: YOUR_SETUP_TOKEN" \
  -d '{
    "url": "YOUR_ENDPOINT_URL",
    "events": ["deploy.completed", "deploy.failed", "incident.created"],
    "description": "Production notifications"
  }'
Expected output: 
{"webhook_id":"wh_xxxxx","status":"active","events":3,"message":"Webhook registered."}
4

Test your webhook

Send a test event to verify end-to-end delivery:

Terminal 
curl -s -X POST https://quick-start.pages.dev/api/v1/test \
  -H "X-Setup-Token: YOUR_SETUP_TOKEN" \
  -d '{"event":"deploy.completed"}'
Expected output: 
{"delivered":true,"latency_ms":142,"status":200}

Check your endpoint — you should see the test event within a few seconds. If delivery fails, verify your endpoint is publicly reachable and returns a 200 status.

✓

You're all set

Your webhook is live. Relay will send notifications to your endpoint whenever the subscribed events occur. To manage your webhooks, events, and delivery logs, visit your Relay dashboard.

Event types reference → Payload security → Retry policy →