Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adrian.secureagentics.ai/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let Secureagentics push event notifications directly to your systems in real time. When a monitored event occurs — such as an alert firing or a policy violation — Secureagentics sends an HTTP POST request containing event details to a URL you specify. Use webhooks to trigger your own workflows: create tickets, notify on-call teams, update dashboards, or feed events into a SIEM.

​
Supported events

Event typeWhen it fires
alert.triggeredA configured alert fired based on your alert rules.
policy.violatedAn agent action violated an active security policy.
agent.registeredA new agent was registered with your workspace.
agent.errorAn agent reported an error event.
You subscribe to specific events when you create a webhook. Secureagentics only sends requests for the event types you select.

​
Create a webhook

1

Open webhook settings

Go to Settings → Webhooks in the Secureagentics dashboard, then click Add webhook.
2

Enter your endpoint URL

Enter the full HTTPS URL of the endpoint that will receive webhook events. The URL must be publicly accessible and respond to POST requests.
3

Select events

Choose the event types you want to subscribe to. You can select one or more from the supported events list.
4

Add a signing secret (recommended)

Enter a secret string that Secureagentics will use to sign each payload. You use this secret to verify that incoming requests genuinely came from Secureagentics. See Verify webhook signatures for details.
5

Save the webhook

Click Save. Secureagentics will immediately send a test ping to your endpoint to confirm it’s reachable.

​
Webhook payload format

Secureagentics delivers events as JSON objects in the POST request body. All events share the same top-level structure. 
{
  "id": "evt_abc123",
  "type": "alert.triggered",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "alert_id": "alrt_xyz",
    "agent_id": "agt_abc123",
    "details": "Rate limit exceeded: 150 prompts/min"
  }
}
FieldTypeDescription
idstringUnique identifier for this event delivery.
typestringThe event type (see Supported events).
timestampstringISO 8601 timestamp of when the event occurred.
dataobjectEvent-specific payload. Contents vary by event type.
The id field is unique per delivery attempt. If Secureagentics retries a failed delivery, the retry carries the same id. Use this to deduplicate events in your handler.

​
Verify webhook signatures

Secureagentics signs every webhook payload using HMAC-SHA256 and your webhook secret. The signature is sent in the X-Secureagentics-Signature header as a hex digest. Verifying this signature confirms the request came from Secureagentics and that the payload was not tampered with in transit. 
import hashlib
import hmac
from flask import Flask, request, abort

app = Flask(__name__)

WEBHOOK_SECRET = "your-signing-secret"

@app.route("/webhooks/secureagentics", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Secureagentics-Signature", "")
    payload = request.get_data()

    expected = hmac.new(
        WEBHOOK_SECRET.encode("utf-8"),
        payload,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(400, "Invalid signature")

    event = request.get_json()
    print(f"Received event: {event['type']}")

    return "", 200
Always use a constant-time comparison (such as hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js) to prevent timing attacks.

​
Retries

If your endpoint does not respond with a 2xx status code within 10 seconds, Secureagentics treats the delivery as failed and retries it automatically. Secureagentics retries up to 5 times with exponential backoff:
AttemptDelay after previous attempt
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry8 hours
After 5 failed attempts, the delivery is marked as failed and no further retries occur. You can see failed deliveries in the webhook detail view in Settings → Webhooks. To avoid missed events:
  • Respond with 200 as quickly as possible. Offload any processing to a background job.
  • Make your handler idempotent using the event id field to deduplicate retried deliveries.

​
Test your webhook

Use the Send test event button to send a sample payload to your endpoint without waiting for a real event to occur.
  1. Go to Settings → Webhooks.
  2. Click on your webhook to open its detail view.
  3. Click Send test event.
  4. Select an event type to test.
  5. Click Send.
Secureagentics sends a test payload and shows the response status and body returned by your endpoint. Use this to confirm your handler is reachable and processing signatures correctly.