Authdog
Log In

Observability guide

SIEM & Security Events

You can send selected events from an environment to a webhook, Slack, or Datadog.

Start from events you have already seen in Audit, prove the receiver can tell a real delivery from a forged one, and only then subscribe. This is event forwarding. It is not a SIEM product, and it does not promise a fixed schema or a retention period.

Prerequisites

  • An Authdog tenant, project, and environment that is already producing audit activity you can recognize.
  • Console access to Audit and to Notifications → Channels. Channels are plan-gated.
  • For a webhook: an HTTPS endpoint that can read the raw body and return 2xx.
  • For Datadog: an API key, the site you use, and the service, source, and tags you want on the events.
  • A secret manager, and a note on who rotates the signing secret. Rotation kills the previous secret immediately.

Implementation

  1. Look at the events this environment actually emits. Open Audit → Event Types. Read the catalog, the counts, and a sample payload. Subscribe to those names. A guessed event type will sit in the channel forever and never fire.

  2. Write down who owns the receiver. Which team gets paged, how the receiver authenticates Authdog, and how a responder searches for one delivery. If you cannot answer those, you are about to create an alert nobody can act on.

  3. Create the channel from the catalog, not from memory. Choose Webhook, Slack, or Datadog. Name it with the environment and the destination, so "prod-slack" is not ambiguous next quarter. Select event types you saw in step 1. Credentials you store here are secrets. List responses redact them. If you need the value again, you rotate. You do not read it back.

  4. Make the webhook reject anything it cannot verify. Each delivery carries X-Authdog-Signature, X-Authdog-Event-Type, and X-Authdog-Delivery-Id. The v1 signature is HMAC-SHA256 over timestamp + "." + rawBody. Read the raw bytes before you parse JSON. Reject a stale timestamp. Compare the signature in constant time. Store the delivery ID and ignore a repeat. If you re-serialize the JSON and then hash it, every legitimate delivery will look forged.

  5. Parse what is there, and tolerate what is not. Keep the event type, delivery ID, environment, timestamp, and the raw details. Some events have no user, no organization, and no IP. A parser that requires those fields will drop the events you most wanted.

  6. Send a test and watch three places. Enable the channel. Authdog should report success, the destination should show the message, and your signature check should pass. If only one of those is true, stop and fix that hop before you subscribe to more event types.

  7. Cause a real event and find it twice. Sign in, safely, in the same environment. The event should show up in Audit logs first, then at the destination. If Audit has it and the destination does not, the channel's event list is wrong or the receiver is filtering it.

  8. Expect retries, and expect them to look new. A failed webhook retries with exponential backoff, starting at 60 seconds, up to 5 attempts. A manual redelivery is signed again, so the bytes change and your idempotency key has to be the delivery ID, not the body hash.

  9. Rotate only when the receiver is ready for the new secret. There is no grace period. The old secret dies when you rotate. Deploy the receiver with the new secret, rotate, send a test, then redeliver anything that failed in the gap.

Security considerations

  • Limit who can list, edit, or test channels, and who can view signing secrets.
  • Do not log full webhook URLs, API keys, signing secrets, or unredacted personal data.
  • Use HTTPS. Reject a bad signature before you parse or queue the body.
  • Set retention and access control on the destination. Authdog does not give you a retention or compliance guarantee for this path.

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

You cannot send a test. Enable the channel and confirm the credential for that destination is set. A disabled channel or a missing Datadog key fails before any HTTP call.

Every signature fails. You are not hashing the raw bytes, or you are using another channel's secret. Do not parse and re-serialize before the HMAC. Compare against the secret for this channel only.

Tests arrive and real events do not. The selected types do not match what the environment emits. Go back to Audit → Event Types and subscribe to a type you just produced.

The destination was down. Redeliver after it recovers. Your handler should treat a repeated delivery ID as a no-op.

Next steps