Events & webhooks

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

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:

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

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:

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:

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
• API
• Integrations
• Security