About Webhooks
Learn what webhooks are, when to use them, and how to secure a webhook integration.
Webhooks let Blazelock notify your application as soon as something changes. Instead of repeatedly asking for the latest scan status, your system receives an HTTP POST request when a relevant event happens.
For most asynchronous scan flows, this is the more efficient way to stay in sync with Blazelock.
Why Use Webhooks?
- Receive scan updates in near real time instead of waiting for the next polling interval.
- Reduce unnecessary API requests by avoiding repeated status checks for scans that have not changed.
- Trigger downstream workflows automatically when relevant webhook events are delivered.
- Keep your application state and internal systems aligned with the latest scan status.
Getting Started
- Set up an HTTPS endpoint that can receive
POSTrequests from Blazelock. - Enter your webhook URL in the Blazelock Dashboard for the relevant API integration.
- Implement handlers for the webhook events your application needs to process.
Validating webhook signatures is not required to get started, but we strongly recommend it so your application can confirm that incoming events were sent by Blazelock.
Delivery & Retries
Blazelock expects your endpoint to respond with a 2xx status code within 15 seconds. If your endpoint returns a non-2xx response or the request times out, the delivery is treated as failed and retried automatically.
For that reason, webhook handlers should acknowledge the request quickly and move longer-running work into background jobs, queues, or asynchronous workers.
Blazelock currently performs up to 10 delivery attempts in total:
| Attempt | Delay after previous attempt | Approximate time since first attempt |
|---|---|---|
| 1 | Immediately | Immediately |
| 2 | 1 minute | 1 minute |
| 3 | 2 minutes | 3 minutes |
| 4 | 5 minutes | 8 minutes |
| 5 | 10 minutes | 18 minutes |
| 6 | 30 minutes | 48 minutes |
| 7 | 1 hour | 1 hour 48 minutes |
| 8 | 2 hours | 3 hours 48 minutes |
| 9 | 4 hours | 7 hours 48 minutes |
| 10 | 22 hours | 29 hours 48 minutes |
Each delivery attempt is signed individually. That means the webhook timestamp and signature reflect the specific retry attempt that was sent.
Security Matters
Blazelock signs every webhook request and includes security headers that we recommend validating before processing the payload. This helps protect your endpoint against forged requests and replay attacks. Learn more in our Signature Validation guide.
Best Practices
- Validate first: Verify the timestamp and signature before you trust the payload. Learn more in our Signature Validation guide.
- Respond quickly: Return a
2xxresponse as soon as the event has been accepted for processing. - Handle events idempotently: Your endpoint should stay correct even if the same delivery is received more than once.
- Process work asynchronously: Move expensive logic out of the request cycle and into background workers.