Authdog exposes environment activity in two complementary ways:

- **Events API** — pull immutable, cursor-paginated events derived from environment audit-log store.
- **Webhooks** — push selected event types to your HTTPS endpoint through environment notification channel.

Use 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.

Response includes opaque `list_metadata.after`. Pass it unchanged as 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 cursor or construct one yourself.

## Discover event catalog

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

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

## Create webhook channel

Webhooks are generic notification channels scoped to 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`, and `datadog`. Generic webhook and Slack require `webhookUrl`; Datadog requires API key and site configuration. Secret values are not returned by notification-channel list operations.

Use notification-channel endpoints to list, create, update, delete, and test channels. Update is `PUT`; omit `webhookUrl` or `datadogApiKey` to preserve stored secret.

## 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 exact bytes of `t + "." + rawBody`. Verification order:

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

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

Webhook endpoint list API currently returns signing secret. Restrict API token that can call it, never expose response to 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"
```

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 stored payload. Your endpoint must still deduplicate.

## Rotate signing secret

`POST /v1/tenants/{tenantId}/environments/{environmentId}/webhooks/{channelId}/rotate-secret` returns new secret. Previous secret stops being valid immediately, so rotation is not a dual-secret grace period. Coordinate deployment:

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

## Related

- [Audit logs](/docs/audit-logs)
- [API](/docs/api)
- [Integrations](/docs/integrations)
- [Security](/docs/security)