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.

Channel	Delivery	Use case
Webhooks	HTTP POST to your endpoint	Real-time event processing and automation
Email alerts	Email via SES/SNS	Critical notifications for owners and operators

Open https://app.{PUBLIC_DOMAIN}.
Navigate to your handle settings.
Open Notifications.
To add a webhook, enter the endpoint URL and select event types.
To add an email subscription, enter the recipient address and select critical event types.
Optionally configure a custom sender domain under Notification Settings.

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

GET /v2/handles/{handle}/notifications

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

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.

Create request body:

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

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

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.

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

{
  "enabled": true
}

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.

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: exponential backoff (5s, 10s, 20s, 40s, 80s). After 5 failed attempts, a webhook.delivery.terminal_failure event is emitted.

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.

Code	Error	Cause
400	`invalid_endpoint_url`	Endpoint URL is not HTTPS
400	`invalid_email`	Email format is invalid
403	`insufficient_role`	Caller lacks OPERATOR or OWNER role
404	`not_found`	Subscription does not exist