Notifications and Alerting

Use this guide to configure webhook subscriptions, email alerts, and notification settings for your handle.

When to use

• You want to receive real-time events when links are clicked, campaigns change, or issues arise.
• You need to route critical alerts (moderation reports, delivery failures) to email.
• You want to customize the sender domain or notification recipient for your handle.

Notification channels

UI path

1. Open https://app.openanalyst.com.
2. Navigate to your handle settings.
3. Open Notifications.
4. To add a webhook, enter the endpoint URL and select event types.
5. To add an email subscription, enter the recipient address and select critical event types.
6. Optionally configure a custom sender domain under Notification Settings.

Required auth

• OPERATOR-level JWT or above to manage webhook and email subscriptions.
• OWNER-level JWT to modify notification settings (sender domain, notification email).
• CREATOR-level JWT to view the notification catalog (read-only).

API fallback

View all notifications

GET /v2/handles/{handle}/notifications

Returns webhook subscriptions, email subscriptions, owner default email status, and the supported event catalog.

Webhook subscriptions

• POST /v2/handles/{handle}/webhooks — create a subscription. Returns a one-time secret for signature verification.
• GET /v2/handles/{handle}/webhooks — list subscriptions.
• DELETE /v2/handles/{handle}/webhooks/{subscriptionId} — remove a subscription.
• POST /v2/handles/{handle}/webhooks/{subscriptionId}/test — send a test delivery. This returns 202 when dispatch is accepted, not when your endpoint has successfully processed the request.

Create request body:

{
  "endpointUrl": "https://example.com/hooks",
  "eventTypes": ["link.clicked", "campaign.health_changed"]
}

Use "*" in eventTypes to subscribe to all events.

Email subscriptions

• POST /v2/handles/{handle}/notifications/email-subscriptions — add a recipient for critical alerts.
• DELETE /v2/handles/{handle}/notifications/email-subscriptions/{subscriptionId} — remove.
• POST /v2/handles/{handle}/notifications/email-subscriptions/{subscriptionId}/test — send a test.

Owner default email

PUT /v2/handles/{handle}/notifications/owner-default-email

{
  "enabled": true
}

Notification settings

• GET /v2/handles/{handle}/notification-settings — view sender domain, notification email, effective recipient.
• PUT /v2/handles/{handle}/notification-settings — update sender domain or notification email.

Webhook delivery format

Each delivery includes these headers:

• x-arjun-signature: HMAC-SHA256 signature (sha256={hex}) for verifying authenticity.
• x-arjun-event-type: The event type (e.g., link.clicked).
• x-arjun-attempt: Delivery attempt number (1 through 5).

Payload:

{
  "id": "evt_...",
  "type": "link.clicked",
  "handle": "acme",
  "occurredAt": "2026-02-25T12:00:00Z",
  "payload": { }
}

Retry policy: up to 5 total attempts. Retryable failures are retried after 5s, 10s, 20s, and 40s. Most deterministic 4xx responses are treated as terminal immediately. After terminal classification, a webhook.delivery.terminal_failure event is emitted.

Use Webhook Delivery and Failure Handling for the full delivery contract, retry matrix, and debugging checklist.

Critical event types (email-eligible)

These events can trigger email alerts:

• webhook.delivery.terminal_failure — a webhook endpoint failed all retries.
• moderation.report.opened — a content report was submitted.
• moderation.escalation.created — a report was escalated.
• destination_domain.risk_changed — a link destination domain risk score changed.

Common errors

Related:

• API Tokens and Automations
• Webhook Delivery and Failure Handling
• API Auth and Error Model
• Troubleshooting and Support