Webhooks
rickub POSTs a JSON payload to your URL when things happen — pushes, merge requests, issues, CI runs, releases, membership — so your own services can react.
What a webhook is
A webhook is a URL you register against a repository or an organization. When a subscribed event happens, rickub POSTs a JSON payload to that URL out of band — your service wakes up and reacts, no polling needed. Common uses: mirroring pushes, pinging a chat room on a release, triggering a deploy after CI goes green, keeping an external tracker in sync with issues.
Webhook management lives in Settings → Webhooks — repository webhooks on the repository, organization webhooks on the org. Setting one up requires admin access to the repository or org.
Events you can subscribe to
A webhook subscribes to any subset of:
| Event | Fires when |
|---|---|
push |
commits are pushed to the repository |
merge_request |
a merge request is opened, closed, merged, or reopened |
issues |
an issue is opened, closed, reopened, or commented on |
ci_run |
a workflow run completes |
release |
a release is published (a draft turning published fires too) |
member |
someone is added to or removed from an organization |
A test ping button on the settings page sends a synthetic ping event so you can verify the wiring before anything real fires.
The payload
Every delivery is a JSON envelope naming what happened and who acted:
{
"event": "push",
"action": "",
"sender": "octocat",
"repository": { "owner": "acme", "name": "api", "…" : "…" },
"data": { "…": "…" }
}
Three headers accompany the body:
X-Rickub-Event— which event fired (the same keys as the table above).X-Rickub-Delivery— a unique id for this delivery, so your receiver can deduplicate.X-Rickub-Signature-256—sha256=<hmac>of the raw body, keyed with the webhook's signing secret. Verify it before trusting a payload.
If you chose the application/x-www-form-urlencoded content type, the same JSON arrives wrapped in a payload= form field — the GitHub-compatible shape, so existing receivers often work unchanged.
The signing secret is shown once, at creation — store it somewhere safe. Rotating it issues a new secret the same way. A receiver that verifies signatures should refuse deliveries that are missing the header: a request with no signature is not from rickub.
Deliveries: logs, retries, redelivery
Every attempt is logged on the webhook's settings page with its response status and duration — and a failed one shows the error, so "the receiver answered 500" and "the hostname did not resolve" look different. A delivery times out after 10 seconds; a receiver that does slow work should acknowledge fast and process asynchronously.
Nothing is auto-retried: if a delivery fails, fix the receiver and click Redeliver on the logged attempt to send the same payload again.
URLs are validated
Payload URLs must be public HTTPS (or HTTP) endpoints: loopback, link-local and private-network addresses are refused at save time, so a webhook cannot be pointed at rickub's own internals or at your cluster's metadata service. Point webhooks at a host the public internet can reach.