Events & webhooks

Authdog exposes environment activity in two complementary ways:

• Events API: pull immutable, cursor-paginated events derived from the environment's audit-log store.
• Webhooks: push selected event types to your HTTPS endpoint through an environment notification channel.

Use the Events API for backfills and reconciliation. Use webhooks for low-latency reactions. For reliable integrations, use both.

List events

curl --get \
  "https://api.authdog.com/v1/tenants/$TENANT_ID/environments/$ENVIRONMENT_ID/events" \
  -H "Authorization: Bearer $AUTHDOG_API_TOKEN" \
  --data-urlencode "rangeStart=2026-07-01T00:00:00Z" \
  --data-urlencode "events=SIGNIN_SUCCESS,NEW_USER" \
  --data-urlencode "limit=100"

Each event contains:

• id: event identifier
• event: canonical event type
• category: optional category
• created_at: event time
• organization_id: optional organization context
• data: source payload plus available user, provider, IP, and user-agent context

limit defaults to 20 and cannot exceed 100. rangeStart is inclusive; rangeEnd is exclusive. events and categories accept comma-separated values.

The response includes an opaque list_metadata.after cursor. Pass it unchanged as the next request's after value:

curl --get \
  "https://api.authdog.com/v1/tenants/$TENANT_ID/environments/$ENVIRONMENT_ID/events" \
  -H "Authorization: Bearer $AUTHDOG_API_TOKEN" \
  --data-urlencode "after=$AFTER_CURSOR" \
  --data-urlencode "limit=100"

Stop when list_metadata.after is null. Never decode the cursor or construct one yourself.

Discover the event catalog

curl \
  "https://api.authdog.com/v1/tenants/$TENANT_ID/environments/$ENVIRONMENT_ID/events/types" \
  -H "Authorization: Bearer $AUTHDOG_API_TOKEN"

The catalog returns event/category pairs and categories. Build subscription UI and filters from this response. Do not assume the examples on this page are complete.

Create a webhook channel

Webhooks are generic notification channels scoped to an environment:

curl -X POST \
  "https://api.authdog.com/v1/tenants/$TENANT_ID/environments/$ENVIRONMENT_ID/notification-channels" \
  -H "Authorization: Bearer $AUTHDOG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production identity events",
    "type": "webhook",
    "enabled": true,
    "webhookUrl": "https://example.com/authdog/webhooks",
    "eventTypes": ["SIGNIN_SUCCESS", "NEW_USER"],
    "channels": []
  }'

Channel types are webhook, slack, datadog, sysdig, splunk, sumologic, and sentinel. Generic webhook and Slack require webhookUrl; the SIEM types have their own required fields (see below). Secret values are not returned by notification-channel list operations; each response instead includes a *Configured boolean per secret.

Use the notification-channel endpoints to list, create, update, delete, and test channels. Update is PUT; omit a stored secret (webhookUrl, datadogApiKey, sysdigApiToken, splunkToken, sumoUrl, or sentinelSharedKey) to preserve it.

Stream events to a SIEM

The SIEM channel types forward the same event stream to your log platform. A SIEM channel with an empty eventTypes array drains all events; list event types to filter.

• datadog: Logs intake. Requires datadogApiKey. Optional datadogSite (defaults datadoghq.com), datadogService, datadogSource, datadogTags.
• sysdig: Events API. Requires sysdigApiToken. Optional sysdigRegion (defaults us1), sysdigSource, sysdigTags.
• splunk: HTTP Event Collector. Requires splunkToken and splunkUrl (HEC base URL, host[:port]). Optional splunkIndex, splunkSourcetype (defaults authdog:audit), splunkSource.
• sumologic: HTTP Source. Requires sumoUrl; the collector URL is itself the credential, so treat it as a secret. Optional sumoSourceCategory, sumoSourceName, sumoSourceHost.
• sentinel: Microsoft Sentinel through the Azure Log Analytics Data Collector API. Requires sentinelWorkspaceId (workspace GUID) and sentinelSharedKey (workspace primary or secondary key). Optional sentinelLogType sets the custom table name (alphanumeric, defaults AuthdogAudit; Azure stores records as <name>_CL).

curl -X POST \
  "https://api.authdog.com/v1/tenants/$TENANT_ID/environments/$ENVIRONMENT_ID/notification-channels" \
  -H "Authorization: Bearer $AUTHDOG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security events to Sentinel",
    "type": "sentinel",
    "enabled": true,
    "sentinelWorkspaceId": "12345678-abcd-ef01-2345-6789abcdef01",
    "sentinelSharedKey": "<workspace shared key>",
    "sentinelLogType": "AuthdogAudit",
    "eventTypes": []
  }'

SIEM deliveries use the platform's native authentication instead of X-Authdog-Signature, and they participate in the same delivery records, retry, and redelivery flow described below. Sentinel redelivery re-signs the stored payload with the current shared key.

Verify webhook signatures

Generic webhook deliveries include:

• X-Authdog-Signature: t=<unix>, v1=<hex>
• X-Authdog-Event-Type
• X-Authdog-Delivery-Id

v1 is HMAC-SHA256 over the exact bytes of t + "." + rawBody. Verification order:

1. Read the raw request body before JSON parsing.
2. Parse the timestamp and v1 from the signature header.
3. Reject timestamps outside your replay tolerance.
4. Compute HMAC-SHA256 with the endpoint's signing secret.
5. Compare digests using constant-time comparison.
6. Only then parse and process the JSON.

Store the delivery ID and make your handler idempotent. Retries and manual redelivery can send the same logical event more than once.

The webhook channel list API currently returns the signing secret. Restrict the API token that can call it, never expose the response to a browser, and avoid logging it.

Delivery and retry behavior

Any 2xx response is success. Failed deliveries are recorded and retried with exponential backoff beginning at 60 seconds, for at most five total attempts. Delivery records include status, attempts, response status, error, last attempt, and next retry time.

List delivery records:

curl --get \
  "https://api.authdog.com/v1/tenants/$TENANT_ID/environments/$ENVIRONMENT_ID/webhooks/deliveries" \
  -H "Authorization: Bearer $AUTHDOG_API_TOKEN" \
  --data-urlencode "status=failed" \
  --data-urlencode "limit=100"

The endpoint supports channelId, status, offset, and limit up to 200. A recorded delivery can be manually redelivered:

POST /v1/tenants/{tenantId}/environments/{environmentId}/webhooks/deliveries/{deliveryId}/redeliver

Redelivery re-signs the stored payload. Your endpoint must still deduplicate.

Rotate the signing secret

POST /v1/tenants/{tenantId}/environments/{environmentId}/webhooks/{channelId}/rotate-secret returns a new secret. The previous secret stops being valid immediately, so rotation has no dual-secret grace period. Coordinate the deployment:

1. Pause or tolerate failed processing.
2. Rotate the secret.
3. Update the receiver immediately.
4. Send a test delivery.
5. Redeliver failed records after verification succeeds.

Related

• Audit logs
• API
• Integrations
• Security