Getting Started with RelayBird
RelayBird receives webhook events at a unique ingest URL and delivers them to one or more destination URLs — with retries, HMAC signing, and a full delivery log. This guide walks you through the dashboard flow.
1. Sign in
Go to https://relay.relaybird.dev and click Sign in with Google.
After sign-in you land on the deliveries tab. Your plan and current-month usage are shown in the header: Plan: free · 0 / 1,000 events this month.
Free vs Pro
| Free | Pro | |
|---|---|---|
| Events / month | 1,000 | 100,000 |
| Event retention | 3 days | 30 days |
| Destinations per source | 1 | Unlimited |
| Failure alerts | — | ✓ |
| Routing / filtering | — | ✓ |
| Per-source retry policy | — | ✓ |
2. Create a source
Click the sources tab → fill in Name and Destination URL → click Create source.
The panel that appears shows your ingest URL (https://relay.relaybird.dev/ingest/<source_id>) and the destination's signing secret (whsec_…). Copy the signing secret now — it is only shown in full at creation time (you can re-reveal it later from the destination's secret button).
3. Send your first event
Point your upstream provider (Stripe, GitHub, Shopify, …) at the ingest URL, or send a test event with curl:
curl -X POST https://relay.relaybird.dev/ingest/<source_id> \
-H "content-type: application/json" \
-d '{"hello": "world"}'
# → {"event_id":"...","status":"accepted","fanout":1}You can also use the ⚡ send test event button on any source card; it posts {"test":true,"sent_from":"dashboard"} and reports how many destinations received it.
RelayBird returns 202 immediately. The worker delivers the event asynchronously, typically within a second.
4. Watch deliveries
Switch to the deliveries tab. Each row shows:
- A colour LED: pending (yellow), delivering (blue, pulsing), delivered
(green), failed (red).
- The short event ID → source ID, attempt count, HTTP status code, and age.
Click any row to open the detail pane:
- Metadata: status, attempt count, destination URL, timestamps.
- Attempt timeline: each attempt with its HTTP status, error (if any), and
latency.
- Payload: the raw inbound body + request headers.
- ↻ replay button: re-queues the delivery as a new
pendingattempt
(same event, same destination — does not create a new event row).
Use the status chips at the top of the list to filter by pending, delivering, delivered, or failed.
5. Add destinations and routing filters (Pro)
A source can fan-out to multiple destinations. Each delivery is independent: separate retries, separate signing secret, separate filter.
To add a destination, open the sources tab, find the source card, enter a URL in the add a destination input, and click + add. Save the signing secret that appears.
Free plan: each source is limited to 1 destination. Adding more requires
upgrading to Pro.
Routing / filtering (Pro)
Click the filter button on any destination row to open the filter editor. Choose Match a JSON body field or Match a header, then enter:
- field: dot-path into the JSON body (e.g.
type, ordata.object.status)
or the header name (e.g. x-github-event).
- allowed values: comma-separated list of exact values or prefix wildcards
(e.g. payment.succeeded, payment.failed, invoice.*).
Events that don't match are not delivered to that destination (but are still delivered to other destinations whose filter matches, or to unfiltered ones). Click clear filter to receive all events again.
6. Inbound signature verification
By default RelayBird accepts any request posted to an ingest URL (the unguessable source ID is the credential). Inbound verification adds an optional extra layer: RelayBird checks that the incoming webhook was actually signed by the upstream provider (Stripe, GitHub, …) using a shared secret, so a leaked ingest URL alone cannot inject arbitrary events.
To enable: sources tab → source card → inbound verification → configure → choose a mode and paste the provider's signing secret.
Verification modes
| Mode | Behaviour |
|---|---|
| off (default) | No check — all requests accepted. |
| monitor | Signature is checked; result is recorded on the event. Requests are always accepted regardless of the outcome. |
| enforce | Invalid or missing signature → HTTP 401; event is not stored, not delivered, and not counted against your monthly quota. |
Start with monitor to confirm signatures pass before switching to
enforce — a misconfigured secret in enforce mode silently drops all
provider events.
Supported providers
| Provider | Signature header | Signed payload |
|---|---|---|
| Stripe | Stripe-Signature (t=…,v1=…) | {timestamp}.{raw_body} — 5-min replay window |
| GitHub | X-Hub-Signature-256 (sha256=…) | Raw body only |
| Shopify | X-Shopify-Hmac-Sha256 (base64) | Raw body only |
| Slack | X-Slack-Signature (v0=…) + X-Slack-Request-Timestamp | v0:{timestamp}:{raw_body} — 5-min replay window |
| Custom | Any header you specify | Configurable (algo, encoding, prefix, template) |
RelayBird pre-fills the algorithm, header name, encoding, and payload template for each preset. Choose Custom to set every field manually: algorithm (sha256 or sha1), encoding (hex or base64), prefix to strip (e.g. sha256=), signed-payload template (e.g. {body} or {ts}.{body}), and an optional timestamp header for replay protection.
The inbound sig cell in the delivery detail pane shows the result per event: verified ✓, invalid ✗, or not checked (off mode). This is visible in both monitor and enforce modes.
7. Connecting providers that require URL verification (handshake)
Some providers — Slack, Meta/Facebook/WhatsApp/Instagram, and generic webhooks that echo a challenge field — will not activate a webhook endpoint until they receive a specific response to a challenge request. RelayBird handles this automatically once you configure handshake mode on a source.
To enable: sources tab → source card → handshake / url verification → configure → choose the mode, optionally enter a verify token, then paste the source's ingest URL into the provider's webhook settings.
Slack (URL verification)
Slack sends a POST with "type": "url_verification" and a "challenge" field when you add a new Request URL in Slack's Event Subscriptions settings.
1. Set handshake mode to slack. No token is needed for Slack. 2. Paste the ingest URL into Slack's Event Subscriptions → Request URL. 3. RelayBird replies {"challenge": "<value>"} — Slack marks the URL as verified.
From this point on, normal Slack events (message, reaction, etc.) flow through as regular stored events. Only the exact url_verification shape triggers the handshake path; all other Slack events are stored and forwarded normally.
Meta / Facebook / WhatsApp / Instagram
Meta sends a GET request with hub.mode=subscribe, hub.verify_token=<t>, and hub.challenge=<v> when you save the webhook URL in the developer console.
1. Set handshake mode to meta / facebook and enter the verify token you chose in Meta's dashboard into the token field. 2. Paste the ingest URL into Meta's webhook callback URL field. 3. RelayBird responds with the plain-text hub.challenge value — Meta activates the endpoint. If the token does not match, RelayBird returns HTTP 403.
POST events from Meta flow through as normal stored events after verification.
Echo (generic)
For services that POST a JSON body containing a field you should echo back:
1. Set handshake mode to echo (generic). 2. Enter the JSON field name to echo in the field input (e.g. challenge). 3. Optionally enter a shared token in the token field; this value is not currently used by the echo check itself but is stored for reference. 4. When the provider sends a POST whose JSON body contains that exact field, RelayBird responds with the field's value as plain text.
Any POST that does not contain the configured field is stored as a normal event.
Events are never swallowed by accident. Only the exact challenge shape
triggers the handshake path — RelayBird refuses to silently discard a normal
event because a JSON key happens to match.
8. Per-source retry policy (Pro)
By default every source uses up to 12 attempts with an exponential backoff starting at 5 s and capping at 6 h. Pro accounts can override this per source from the source card's retry policy row.
Max attempts — how many total attempts before marking the delivery failed (1–24; leave blank for the global default of 12).
Backoff profile — controls the gap between retries:
| Profile | Use when | Approx. range |
|---|---|---|
normal (default) | Most destinations | 5 s → 6 h |
fast | Destination recovers in seconds/minutes | 2 s → 10 min |
slow | Flaky endpoint — avoid hammering it | 15 s → 12 h |
Jitter (±50 %) is always applied so retries from many deliveries don't all fire at the same instant. Changing the policy takes effect on the next scheduled attempt; in-flight deliveries keep their current schedule.
Click reset to default to remove the per-source policy and fall back to the global settings.
9. Failure alerts (Pro)
When a delivery permanently fails (all retry attempts exhausted), RelayBird can notify you via a Slack or Discord incoming webhook, or any endpoint that accepts a {"text":…} / {"content":…} JSON POST.
Open the alerts tab → enter your webhook URL → toggle alerts enabled → click Save. Click ⚡ send test alert to verify the connection.
Alerts are batched and sent at most once per minute.
10. Verify the signature
Every outbound delivery includes an X-Webhook-Signature header so your receiving endpoint can confirm the request genuinely came from RelayBird and hasn't been tampered with. See Signature Verification for the exact algorithm and ready-to-use code examples.
11. Programmatic access (API keys)
The dashboard uses your Google login. For scripts and CI, create an API key:
Dashboard → keys tab → Create key — copy the whr_… key immediately, it is shown only once.
Then use it as a Bearer token:
KEY=whr_...
# List your sources
curl -s https://relay.relaybird.dev/v1/sources \
-H "Authorization: Bearer $KEY"
# Create a source
curl -s -X POST https://relay.relaybird.dev/v1/sources \
-H "Authorization: Bearer $KEY" \
-H "content-type: application/json" \
-d '{"name":"orders","destination_url":"https://example.com/hook"}'
# List recent deliveries
curl -s "https://relay.relaybird.dev/v1/deliveries?limit=20" \
-H "Authorization: Bearer $KEY"
# Replay a delivery
curl -s -X POST https://relay.relaybird.dev/v1/deliveries/<delivery_id>/replay \
-H "Authorization: Bearer $KEY"The full API is documented at https://relay.relaybird.dev/docs.
12. Plan limits & quota
When your monthly event limit is reached, ingest returns HTTP 402 and the event is rejected (not stored, not delivered, not counted). The counter resets at the start of each calendar month (UTC). Upgrading to Pro raises the limit immediately.
See Plan limits & quota for the full details, the 402 response body shape, and how to monitor usage via the API.