Skip to main content
Gecko can push events to your systems as scans run and findings change: page a channel when a scan fails, open a workflow when a critical lands, or mirror status changes into an internal system of record. Manage endpoints in Settings → Webhooks (permission: 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.
The signing secret is shown exactly once, when you create the endpoint or rotate its secret. Store it securely; Gecko never shows it again.

Verify signatures

Every delivery is signed so you can prove it came from Gecko and wasn’t tampered with. The X-Gecko-Signature header has the form:
where the HMAC-SHA256 is computed over <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 2xx quickly 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

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.
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.
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.