A webhook is an HTTP request that one system sends to a URL you provide when something happens, such as a new finding or a ticket status change. It pushes events to you instead of making you ask. Security tools use webhooks to feed tickets, chat and workflows.
Definitions
- Event: something that happened, such as "finding created" or "issue transitioned".
- Payload: the data sent with the event, usually JSON.
- Receiver or endpoint: the URL that accepts the call.
- Delivery: one attempt to send an event to the receiver.
- Signature: a value computed from the payload and a shared secret, so the receiver can check who sent it.
How a security flow works
- A scan finishes and finds a new critical issue.
- The tool sends an event to your receiver.
- The receiver checks the signature, saves the event, and answers quickly.
- A background worker creates a ticket, posts to chat or starts a workflow.
Going the other way, a ticket system can send an event when someone changes a status, and the security tool can update the finding.
What the receiver must do
GitHub's webhook guidance gives a good baseline that applies broadly. Respond with a 2XX status within 10 seconds, or the delivery counts as failed. Acknowledge fast and process in a background queue so later deliveries are not blocked. Use a random, high entropy secret to verify deliveries, store it where your server can read it, and keep credentials out of the payload URL. Use the delivery id header to spot duplicates, since a redelivery keeps the same value.
| Concern | Practice |
|---|---|
| Authenticity | Verify the signature against the raw body |
| Speed | Return 2XX quickly, work later |
| Duplicates | Store delivery ids and ignore repeats |
| Secrets | Keep out of URLs and logs |
| Outages | Expect redelivery and gaps |
Webhook versus API call
A webhook is the system calling you. An API call is you calling the system. Most real integrations use both: the webhook says something changed, then you call the API to fetch the full current state. That second step also protects you from acting on a stale or forged payload. See webhook or polling for when each fits.
Try it yourself
In the demo, watch how a scan result moves through monitoring. Each state change is the kind of event a webhook would carry.
Click through it at your own pace, or open it full screen.
Quick check
Is a webhook the same as an API?
No. A webhook is the sender calling your URL when an event occurs. An API is something you call to ask for data or to change something.
Why answer a webhook before doing the work?
The sender expects a quick reply and may treat a slow one as a failure and retry. Queue the work and reply first.
Safeguard offers compliance and evidence automation and continuous scanning, and you can try a free scan at gold.safeguard.sh/scan.
Sources
- GitHub Docs, Best practices for using webhooks
Last reviewed: 19 October 2026.
