Authdog exposes environment activity in two complementary ways:

- **Events API**: pull immutable, cursor-paginated events derived from the environment's [audit-log](/docs/audit-logs) 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

```bash
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:

```bash
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

```bash
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:

```bash
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`).

```bash
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:

```bash
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](/docs/audit-logs)
- [API](/docs/api)
- [Integrations](/docs/integrations)
- [Security](/docs/security)