Help
/
CI & Webhooks
Login
Manage Webhooks from the CLI

The rad webhooks CLI manages webhook configuration from a repo working copy — useful for scripting or infrastructure-as-code. It’s the alternative to the dashboard; if you’d rather click than type, the dashboard guide is the recommended path and covers the same delivery.

Before you start

  • Ensure you have rad-webhooks CLI installed:

curl -sSfL https://index.radicle.garden/raw/rad:z2jrMkSbYgoVVB2tnzDaja55iX42R/head/install.sh | bash

  • Verify everything is set up correctly, by running: rad webhooks . You should see the CLI usage instructions.

Smoke test (5 minutes)

Enable a webhook on a repo seeded by your Radicle Garden node and verify it fires, using webhook.site as a throwaway receiver. A good check before you wire up a real CI system.

  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. (The dashboard lets you edit a webhook in place instead, and toggle it active/inactive without deleting it.)

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