Alert webhooks

Aepto POSTs signed JSON to your HTTPS URL when subscribed events fire. Manage webhooks in the app or via the Platform API. End-user UI steps: Docs - Alert webhooks.

Auth and scopes

• API calls use Authorization: Bearer ... (API key or Connect token).
• Read: webhooks:read. Write: webhooks:write.
• Alert webhooks require a plan that includes them.
• POST creates require an Idempotency-Key header.

Manage via API

Base path: https://app.aepto.com/api/v1. Full table: Endpoints — Alert webhooks.

curl -sS -X POST "https://app.aepto.com/api/v1/alert-webhooks" \
  -H "Authorization: Bearer aep_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"My receiver","url":"https://example.com/hooks/aepto"}'

Subscriptions

POST /alert-webhooks/{id}/subscriptions JSON fields:

• feature_type - category to receive (default website_monitoring)
• scope - global, domain, or monitoring
• domain_id / monitoring_id - required when scope needs them
• event_types - optional filter; omit for all events in that feature
• is_enabled - optional (default true)
• bulk_account_wide - true creates one global subscription per allowed feature type

feature_type values include: website_monitoring, content_monitoring, renewal_reminders, domain_notifications, theft_guard, dns_monitoring, email_deliverability_alerts, incident_reminders, pagespeed_alerts, domain_watch, domain_expense_reports, api_rate_limits.

Some features are account-wide only (global): Domain Watch, expense reports, incident reminders, and API Rate Limits. Per-monitor scope applies to website and content monitoring.

Outbound delivery

Aepto sends POST to your URL with JSON body and these headers:

• Content-Type: application/json
• X-Aepto-Event-Id - unique event id
• X-Aepto-Event-Type - e.g. monitoring.downtime
• X-Aepto-Signature - t=<unix>,v1=<hex>
• Idempotency-Key - same as event id (safe to dedupe)
• User-Agent: Aepto-Webhooks/1.0

Envelope (schema_version: 1):

{
  "schema_version": 1,
  "event_id": "...",
  "event_type": "monitoring.downtime",
  "occurred_at": "2026-01-15T12:00:00Z",
  "user": { "id": 123, "public_ref": "user:123" },
  "resource": { "type": "monitoring" },
  "data": { }
}

Monitoring events use resource.type monitoring and types such as monitoring.downtime, monitoring.recovery, monitoring.ssl_expiry, monitoring.slow_response (plus sample monitoring.test). Other families use resource.type notification and event_type shaped like {feature_type}.{template_key} (for example dns_monitoring.dns_change_alert, theft_guard.general_security_alert).

Respond with 2xx quickly. Failed deliveries are retried with backoff; repeated failures can pause the endpoint until you fix and re-enable it.

Verify signatures

1. Read the raw request body (bytes), not a re-serialized JSON object.
2. Parse X-Aepto-Signature for t (timestamp) and v1 (hex HMAC).
3. Reject if t is too far from your clock (recommended: a few minutes).
4. Compute HMAC-SHA256(signing_secret, t + "." + raw_body) as hex.
5. Compare to v1 with a constant-time equals.

// Node.js sketch
const crypto = require('crypto');
function verify(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.trim().split('='))
  );
  const t = parts.t;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Secrets

• Store signing_secret from create or rotate in your secrets manager. It is shown once.
• Never log the full secret or put it in client-side code.
• Rotate with POST /alert-webhooks/{id}/rotate-secret if a secret may be exposed.

App UI

In the dashboard: Domains → Alert webhooks. Use Send sample and the delivery log while wiring your receiver. Product walkthrough: Alert webhooks (Docs).

FAQ

More answers: FAQ hub.