Authdog
Observability guide

SIEM & Security Events

Authdog can route selected environment events to generic webhooks, Slack, or Datadog notification channels. Treat this as an event-forwarding integration, not a promise of a universal SIEM exporter or fixed normalized schema. Build subscriptions from Authdog's event catalog, inspect observed payloads, verify delivery security, and validate end-to-end ingestion in the destination you operate.

Prerequisites

  • An Authdog tenant, project, and environment producing representative audit activity.
  • Console access to Audit and Notifications → Channels. Notification Channels are plan-gated in the current console.
  • For a generic webhook, an HTTPS endpoint that can preserve the raw request body and return a 2xx response.
  • For Datadog, an API key, supported Datadog site, and your chosen service, source, and tags.
  • Destination-side access to search ingested events and inspect rejected requests.
  • A secret manager and a runbook for signing-secret rotation.

Start with a non-production environment. Generate one known event for each workflow you intend to forward, then inspect it in Audit before selecting it for delivery.

Implementation

  1. Discover actual event types. In Audit → Event Types, search the environment's catalog and observed activity. Select a type to inspect its count, recent sample, and inferred schema. The schema explorer merges at most 20 observed samples and is explicitly a prototype; use it to understand current payloads, not as a permanent contract. Do not subscribe to guessed names copied from examples.

  2. Define destination ownership. Record which team owns the receiver, which environment it accepts, how it authenticates Authdog deliveries, what data it stores, and how responders search it. Decide whether the destination needs every observed event or a narrower set of authentication and administrative signals.

  3. Create a channel. In Notifications → Channels, choose:

    • Webhook for a custom HTTPS receiver.
    • Slack for notifications delivered through a Slack webhook URL.
    • Datadog to send authentication event logs using a Datadog API key and site configuration.

    Name the channel with environment and destination, keep it disabled while entering configuration if your workflow permits, and select event types based on the catalog. Stored webhook and Datadog credentials are treated as secrets and are omitted or redacted by normal channel-list responses.

  4. Secure a generic webhook receiver. Generic deliveries include X-Authdog-Signature, X-Authdog-Event-Type, and X-Authdog-Delivery-Id. The signature's v1 value is HMAC-SHA256 over the exact bytes of timestamp + "." + rawBody.

    Receiver order matters: read raw bytes before JSON parsing, parse timestamp and digest, reject timestamps outside your replay tolerance, compute HMAC with the endpoint secret, compare in constant time, and only then parse the body. Store delivery IDs and make processing idempotent because retries and manual redelivery can repeat a logical event.

  5. Map defensively. Preserve the Authdog event type, delivery ID, environment context, timestamp, and raw details available in the observed payload. Permit missing and additional fields. Add destination-side fields such as ingestion time or parser version in your own namespace. Do not assume every event has user, organization, provider, IP, or user-agent data.

  6. Send a test. Enable the channel and use its test action. A webhook or Slack channel requires a configured URL; Datadog requires a configured API key. Confirm Authdog reports success, the destination receives the message, signature validation passes for generic webhooks, and the event can be found using a unique test marker.

  7. Validate real events. Perform a safe test sign-in or administrative change in the same environment. Confirm the event appears first in Audit logs, then in the destination. Compare type, timestamp, environment, and source details. A successful test message does not prove that event subscriptions are correct.

  8. Operate deliveries. Review recorded delivery attempts by channel and status. Failed webhook deliveries are retried with exponential backoff beginning at 60 seconds, for at most five total attempts. A recorded delivery can be manually redelivered and is re-signed, so deduplication remains required.

  9. Rotate deliberately. Signing-secret rotation invalidates the previous secret immediately; there is no documented dual-secret grace period. Coordinate receiver deployment, rotate, update the secret promptly, send a test, and redeliver failed records only after verification succeeds.

Security considerations

Restrict who can list or edit channels, test destinations, view signing secrets, or use API tokens. Never log full webhook URLs, Datadog keys, signing secrets, signature inputs, or unredacted personal data. Apply egress and destination allowlists where your infrastructure supports them.

Use HTTPS and reject invalid signatures before parsing or queueing generic webhook content. Timestamp checks limit replay but do not replace delivery-ID deduplication. Return 2xx only after reaching your chosen durable processing boundary; otherwise Authdog will treat the attempt as successful even if later work is lost.

Set retention, access controls, redaction, and deletion in the destination. Authdog repository material does not establish a retention period, immutability guarantee, compliance status, or SIEM-specific archival policy for this workflow.

Validation checklist

  • Channel belongs to the intended environment and has an unambiguous name.
  • Subscribed event types come from catalog or observed activity.
  • Generic receiver verifies raw-body HMAC, timestamp, and delivery ID.
  • Duplicate delivery produces one downstream action.
  • Test message is visible and searchable at the destination.
  • Real test event matches its Audit source record.
  • Disabled or unselected event types do not create unexpected downstream records.
  • Failed attempts are visible; redelivery succeeds after receiver recovery.
  • Secret rotation test passes and old secret is rejected.
  • Destination retention and access policy are documented independently.

Troubleshooting

If a test cannot be sent, enable the channel and configure its required credential: webhook URL for webhook or Slack, API key and site for Datadog. Confirm Notification Channels are available for the tenant's plan.

For signature failures, verify you used exact raw bytes, the timestamp formatting from the header, the correct channel secret, and constant-time comparison. Parsing and re-serializing JSON before HMAC calculation changes the bytes and invalidates the digest.

If tests arrive but real events do not, check selected event types against Audit → Event Types and generate activity in the same environment. If payload mapping breaks, compare current observed samples and update the defensive parser without dropping unknown fields.

If the destination was unavailable, inspect failed deliveries and redeliver after recovery. Expect duplicates and rely on delivery-ID idempotency.

Next steps