How to test a RelayLink webhook endpoint

Your receiver works from your laptop, but that does not prove RelayLink can reach it, that your deployed code reads the raw body correctly, or that the stored signing secret matches. Test the registered endpoint from the RelayLink account portal before an arriving package depends on it.

The test uses the same delivery path and signing contract as a package notification. Its body carries no package content.

Send the portal test event

1. Sign in to RelayLink in a browser.
2. Open Webhooks from your account.
3. Choose the named receiver you want to exercise.
4. Press its test control.
5. Watch the receiver for a webhook.test POST.

Testing is portal-only, just like creating, disabling, enabling, and deleting a receiver. The test is queued, so the browser action and the POST do not have to happen in the same instant.

If the receiver is switched off, turn it on before testing. If no request arrives, check the receiver's public URL, TLS certificate, network logs, and the latest delivery status shown in RelayLink. Do not send a real package merely to probe the wiring.

Inspect the exact request

The test body has exactly four fields. The identifiers, time, and host below are examples:

{
  "event": "webhook.test",
  "delivery_id": "7f490857-1d61-4bbb-91dc-06c9c67398a8",
  "sent_at": "2027-04-17T09:12:34+00:00",
  "mcp_url": "https://relaylink.example/mcp"
}

There is no package_id, thread_id, sender, topic, recipient, note, TL;DR, or ask. A test handler should branch on the event value rather than trying to parse this as a package envelope.

Every POST also carries this HTTP shape:

Content-Type: application/json; charset=utf-8
Accept: application/json
User-Agent: RelayLink-Webhook/1
X-RelayLink-Event: webhook.test
X-RelayLink-Delivery: 7f490857-1d61-4bbb-91dc-06c9c67398a8
X-RelayLink-Timestamp: 1807953154
X-RelayLink-Signature: sha256=<lowercase hexadecimal HMAC>

X-RelayLink-Delivery matches delivery_id. The timestamp is Unix seconds. Recompute the signature over the untouched request bytes using "{timestamp}.{body}" and the secret shown when this subscription was created. Compare the result in constant time.

Make the handler prove the right things

Pair the live portal test with receiver-side negative and retry tests. Together they should prove that the receiver:

• rejects a bad signature before doing work;
• rejects a timestamp outside your chosen freshness window;
• records the delivery id and a durable downstream work item atomically;
• treats the same delivery id as an already accepted event;
• recognizes webhook.test without trying to fetch a package;
• keeps the secret, full endpoint path, signature, and raw authorization credentials out of logs.

Return a 2xx response once the event is durably accepted. RelayLink does not need a response body and does not follow redirects. A timeout, redirect, or non-2xx response is a failed attempt.

Test retries without creating duplicate work

RelayLink delivery is at-least-once. A failed attempt can return later with the same delivery id and byte-identical body. The timestamp and signature are produced for each POST, so verify each attempt, then deduplicate on the delivery id.

You can exercise that behavior by making the receiver fail once before accepting the event. The safe result is one downstream test record even if your access log shows more than one POST.

With the current defaults, one delivery receives up to six attempts over about an hour. Automatic switch-off is a separate subscription counter: 30 consecutive failed attempts across deliveries. Any accepted 2xx resets that counter.

After the test passes, keep package handling separate. A package.received event is still only an envelope; your worker must fetch the package through the supplied MCP address using the account's separate RelayLink credential. Receiving the webhook alone does not prove that a person or assistant read anything.