This document serves as a comprehensive guide to help you understand and implement webhooks effectively for integrating cybersecurity events, such as from Honeypots and Vulnerability Management, into your systems.
How it Works
Webhooks are user-defined HTTP callbacks that are triggered by specific events in our platform. They provide a powerful way to send real-time data from our platform directly to other applications or services you use. This makes webhooks invaluable for creating integrated and automated workflows tailored to your cybersecurity needs.
Webhooks Flow
Request Access: Since the feature is in beta, it's not visible in the user portal. You need to contact support to enable webhooks for your account.
Registering an Endpoint: Once access is granted, you can register an endpoint URL where you wish to receive webhook notifications.
Event Subscription: Specify which events you want to subscribe to. Each webhook can be tailored to receive specific types of events.
Receiving Events: When an event occurs, our system sends a HTTP POST request to the registered endpoint. The request includes the event details and additional security headers to ensure the data integrity.
Verifying Authenticity: Validate the authenticity of each event by checking the HMAC signature in the 'X-Signature' header against your webhook's secret key.
Terminology
Webhook: A configured endpoint linked to a company with a secret key and a subscription to specific events.
Webhook Event: An occurrence triggering a notification to the webhook, characterized by its name, retries, payload, and status.
Webhook Event Log: Records attempts to deliver an event, documenting each trial with status codes and responses.
Security
Idempotency Key: To prevent duplicate processing, we include a unique
X-Webhook-Event-Idin the header.Preventing Replay Attacks: We mitigate replay threats by appending a timestamp to the header (
X-Timestamp) and body, which are included in the HMAC signature calculation.HMAC Signature: The signature is generated using the complete JSON body (including the event, payload, and timestamp). You can validate this signature using the
X-Signatureheader to ensure data integrity.
Retry Policy
Response Requirement: We require a successful 2xx HTTP response to consider the webhook delivered.
Retry Mechanism: If delivery fails, retries follow an exponential backoff strategy, calculated as
Carbon::now()->addMinutes(2 ** $retries), with a maximum of six attempts.
Rotate Webhook Secret
To rotate a webhook's secret:
Navigate to the webhook configuration in the portal.
Click the 'Refresh' button next to the secret.
A new secret is generated and used for subsequent HMAC signatures.
Testing
A feature in the portal allows you to send a test event (test.webhook-event) to verify your setup.
The test payload will be:
{
"company": "REPLACE_WITH_YOUR_COMPANY_NAME"
}
Tips for Effective Implementation
Confirm that each webhook event is unique using the idempotency key.
Verify the HMAC signature to ensure data integrity.
Subscribe only to necessary events to optimize performance.
Ensure your endpoint uses HTTPS and is not set to localhost or a direct IP address.
Always return a 2xx response to acknowledge successful receipt.
This guide should help you effectively integrate and utilize webhooks within our platform. For further assistance or to request access to the beta, please contact our support team.