webhooks.manage; Pro and Enterprise
plans).
These are outbound events from Gecko to you, not the inbound
repository webhooks your Git provider sends to Gecko.
Event types
Create an endpoint
In Settings → Webhooks, add an endpoint with its URL and the events it should receive, then send a test event to confirm your handler responds. Endpoint URLs must be public HTTPS URLs. Loopback, private, and link-local addresses and internal hostnames are rejected when you create or update the endpoint, and checked again at delivery time, so a DNS change can’t later redirect deliveries into a private network.Verify signatures
Every delivery is signed so you can prove it came from Gecko and wasn’t tampered with. TheX-Gecko-Signature header has the form:
<t>.<body> with your endpoint
secret. Verify every delivery before acting on it:
1
Parse the header
Split on commas:
t is the delivery timestamp, v1 is the signature.2
Recompute the signature
Concatenate the timestamp, a period, and the raw request body, then
compute HMAC-SHA256 with your secret. Use the raw bytes; re-serializing
the JSON will change the signature.
3
Compare timing-safely and reject stale timestamps
Use a constant-time comparison, and reject deliveries older than a few
minutes to block replays.
Delivery and retries
- Respond with a
2xxquickly and process asynchronously; slow handlers get retried as failures. - Failed deliveries are retried with exponential backoff, up to 6 attempts.
- Deliveries can arrive out of order or, after a retry, more than once. Treat handlers as idempotent and use the event’s timestamp, not arrival order, when sequencing matters.
Rotate or revoke
All of these live in Settings → Webhooks:- Pause or narrow: disable the endpoint or change its event list.
- Revoke: delete the endpoint to stop deliveries immediately.
- Rotate the secret: rotating issues a new secret and shows it once. Deploy it to your handler right away, since deliveries are signed with the new secret from then on.
- Redeliver: resend a past delivery from the endpoint’s delivery history.
Troubleshooting
Endpoint creation is rejected
Endpoint creation is rejected
The URL must be public HTTPS. Loopback (
localhost, 127.0.0.1),
private ranges, link-local addresses, and internal hostnames are refused.
For local development, use a tunnel (for example ngrok) that gives you
a public HTTPS URL.Signatures never match
Signatures never match
Almost always a body problem, not a secret problem: verify against the
raw request bytes before any JSON parsing or re-encoding, and make
sure no proxy in front of your handler rewrites the body. Then confirm
you stored the latest secret shown at creation or rotation, not an ID or
the endpoint’s URL.
Deliveries stopped arriving
Deliveries stopped arriving
Check in Settings → Webhooks that the endpoint still exists, that it
hasn’t been disabled, and that your handler returns
2xx fast enough.
An endpoint that fails all 6 attempts for a given event simply misses
that event; deliveries resume with the next one.