Overview#

Webhooks are a powerful way to receive real-time updates from GritivaCore. When specific events occur in your fleet, GritivaCore sends a POST request containing JSON data to a URL you have registered. This document outlines the key aspects of webhooks, including their definition, use cases, operation, common formats, and security considerations.

Webhooks are automated messages sent from apps when something happens. They contain information about the event that triggered them and are sent to a specified URL.

Common use cases for webhooks include:

• Sending Slack notifications for fleet events.
• Custom monitoring solutions that react to fleet changes.
• Syncing fleet state to your Configuration Management Database (CMDB).

Webhooks operate through two main processes: sending and receiving data.

Sending Data#

When an event occurs, GritivaCore sends a POST request to the registered URL with a JSON payload containing event details.

Receiving Data#

The receiving server must handle the incoming POST request and process the JSON data accordingly.

The data sent via webhooks is typically in JSON format. An example payload might look like this:

{
  "event": "vm.online",
  "data": {
    "vm_id": "12345",
    "status": "online"
  }
}

To ensure the security of your webhooks:

• Each delivery includes an X-Gritiva-Signature header, which is an HMAC-SHA256 hash of the raw body computed with your registered secret. Reject any requests that do not match this signature.
• Implement a retry policy with up to 5 attempts and exponential backoff (30s, 2m, 10m, 1h, 6h) before dropping the request.
• Use the Idempotency-Key header to prevent duplicate processing of events.

Webhooks are a critical feature for integrating GritivaCore with other systems. By understanding how they work and implementing best practices for security and reliability, you can effectively utilize webhooks to enhance your fleet management.