Authdog

Observability guide

SIEM & Security Events

Authdog can route selected environment events to generic webhooks, Slack, or Datadog. This guide builds subscriptions from the event catalog, verifies delivery security, and validates end-to-end ingestion; it's an event-forwarding integration, not a universal SIEM exporter with a fixed schema.

Prerequisites

  • An Authdog tenant, project, and environment producing representative audit activity.
  • Console access to Audit and Notifications → Channels (plan-gated).
  • For a generic webhook, an HTTPS endpoint that preserves the raw request body and returns a 2xx response.
  • For Datadog, an API key, supported site, and your chosen service, source, and tags.
  • A secret manager and a runbook for signing-secret rotation.

Implementation

  1. Discover actual event types. In Audit → Event Types, inspect the environment's catalog, counts, and samples. Don't subscribe to guessed names.

  2. Define destination ownership. Record which team owns the receiver, how it authenticates deliveries, and how responders search it.

  3. Create a channel. Choose Webhook, Slack, or Datadog, name it with environment and destination, and select event types from the catalog. Stored credentials are treated as secrets and redacted in list responses.

  4. Secure a generic webhook receiver. Deliveries include X-Authdog-Signature, X-Authdog-Event-Type, and X-Authdog-Delivery-Id. The v1 signature is HMAC-SHA256 over timestamp + "." + rawBody. Read raw bytes before JSON parsing, reject stale timestamps, compare in constant time, and store delivery IDs for idempotency.

  5. Map defensively. Preserve event type, delivery ID, environment, timestamp, and raw details. Permit missing fields, don't assume every event has user, organization, or IP data.

  6. Send a test. Enable the channel and confirm Authdog reports success, the destination receives the message, and signature validation passes.

  7. Validate real events. Perform a safe test sign-in in the same environment and confirm it appears first in Audit logs, then at the destination.

  8. Operate deliveries. Failed webhook deliveries retry with exponential backoff (60s start, 5 attempts max). Manual redelivery re-signs the payload, so deduplication remains required.

  9. Rotate deliberately. Secret rotation invalidates the previous secret immediately, no grace period. Deploy the receiver update, rotate, send a test, then redeliver failed records.

Security considerations

  • Restrict who can list, edit, or test channels, or view signing secrets.
  • Never log full webhook URLs, API keys, signing secrets, or unredacted personal data.
  • Use HTTPS and reject invalid signatures before parsing or queueing webhook content.
  • Set retention and access controls in the destination, Authdog does not establish a retention or compliance guarantee for this workflow.

Validation checklist

  • Channel belongs to the intended environment with an unambiguous name.
  • Subscribed event types come from the catalog or observed activity.
  • Generic receiver verifies raw-body HMAC, timestamp, and delivery ID.
  • Duplicate delivery produces one downstream action.
  • Real test event matches its Audit source record.
  • Secret rotation test passes and old secret is rejected.

Troubleshooting

If a test cannot be sent, enable the channel and confirm the required credential is configured. For signature failures, verify exact raw bytes and the correct channel secret, re-serializing JSON before HMAC calculation invalidates the digest. If tests arrive but real events don't, check selected event types against Audit → Event Types. If the destination was unavailable, redeliver after recovery and rely on delivery-ID idempotency.

Next steps