/
Help
CI & Webhooks
Generic webhooks
Login
Webhooks

Generic Webhook Setup

Enable a webhook on a repo seeded by your Radicle Garden node and verify it fires, using webhook.site as a throwaway receiver. Takes about 5 minutes and is the recommended smoke test before you wire up a real CI system.

Prerequisites → Before you start.

Steps

  1. Confirm your repo is seeded by your Garden node.

  2. Open https://webhook.site. Copy the https://webhook.site/<uuid> URL shown at the top. Leave the tab open.

  3. From your repo working copy, register the webhook. --nid is your Garden node ID — the CLI derives the encryption key from it automatically.

    rad webhooks add \
  --name smoke-test \
  --nid <your node ID> \
  --secret 'any-string-is-fine-here' \
  --url 'https://webhook.site/<uuid>'

  4. Commit and push the config so your node sees it:

    git add .radicle/webhooks/smoke-test.yaml
git commit -m 'Smoke-test webhook'
git push rad

  5. Watch webhook.site — within ~30 s a POST should appear with:

    • x-radicle-event-type: push header,

    • X-Hub-Signature-256: sha256=… (HMAC-SHA256 of the body using your --secret),

    • JSON body containing repository, after, branch, context, commit_status_url.

  6. Clean up:

    rad webhooks delete --name smoke-test
git commit -am 'Remove smoke-test webhook'
git push rad

If nothing arrives, see Troubleshooting.

Tip: You can also use git’s clean/smudge filters to have webhook settings files automatically encrypted/decrypted by means of a .gitattributes entry. See the persistence doc for more details.

Next

Once the smoke test works, you know the delivery path is healthy. Connect a real CI system → Jenkins setup guide.

Manage webhooks

Run the below commands in a working copy of your repo.

The ls/show/delete subcommands use your local private key (default $RAD_HOME/keys/radicle) to decrypt any webhook configuration files found inside of .radicle/webhooks/ in your repo.

rad webhooks ls
rad webhooks show   --name <name>
rad webhooks delete --name <name>

Updating = delete + re-add.

Troubleshooting

Nothing arrives at the webhook URL

  1. rad webhooks ls shows the webhook.

  2. git ls-files .radicle/webhooks shows it on the remote (if not, it wasn’t pushed).

  3. The URL is reachable from your Garden node — not just your laptop.

commit_status_url callback returns 401/403

Signature mismatch. Sign the raw body with HMAC-SHA256, hex digest, lowercase; header format is exactly X-Garden-Signature-256: sha256=<hex>.

“refusing to decrypt” in adapter logs

Wrong --nid at add time — the file was encrypted for a different node. Re-add with the correct NID.

Signature verification failing on the CI side

  • Sign the raw body, not a re-serialized copy.

  • Use a timing-safe comparison (hmac.compare_digest, crypto.timingSafeEqual).

Support

Create a new topic on the #Garden channel on Radicle Zulip.

Help