A webhook quickstart with zero assumed telepathy
- Client
- Relay (spec)
- Year
- 2026
- Niche
- Technical docs
[ The brief ]
Relay guarantees webhook delivery with retries and replay. Their old quickstart assumed you already knew their vocabulary. The spec brief: a new user’s first five minutes, rewritten so nothing is assumed and something works.
[ Craft decisions ]
- →Time-to-first-success is the metric: one endpoint, one event, one visible result.
- →Every code block runs verbatim: copy, paste, watch it work, then learn why.
- →Failure is documented next to success: the three most likely errors, right there.
[ The sample ]
Deliver your first event in 5 minutes
By the end of this page you’ll have an endpoint that receives a test event from Relay, retries automatically if your server flinches, and shows the delivery in your dashboard. You need: a Relay API key (Dashboard → Keys) and any HTTPS endpoint. We’ll use a request bin so you can start before your backend exists.
1. Register an endpoint
curl https://api.relay.dev/v1/endpoints \ -H "Authorization: Bearer $RELAY_KEY" \ -d url="https://your-bin.example.com/hooks" \ -d events="invoice.paid"
Relay replies with an endpoint id (ep_…) and a signing secret (whsec_…). Save the secret now: it’s shown once, and you’ll want it in step 3 to verify that events are really from us.
If it didn’t work
- ✱401 unauthorized: your key is a test key on a live URL, or vice versa. Keys are mode-specific; check the prefix (rk_test_ vs rk_live_).
- ✱422 invalid url: the endpoint must be HTTPS with a valid certificate. Local tunnels (ngrok, cloudflared) work fine.
- ✱Nothing arrived: check Dashboard → Deliveries. If the attempt is there with a red status, the response body will tell you what your server said. It’s usually a 404 route typo. It’s always a 404 route typo.
[ Read it like an editor ]
The reader ships something real before learning any theory, and the error section admits what actually goes wrong. Docs that respect the 2 a.m. debugger earn the daytime purchase.