Events & Alerts

Email infrastructure problems tend to be silent. A DNS record gets misconfigured during a migration, and no one notices until customers complain they're not receiving emails. A new marketing tool starts sending as your domain without proper authentication, and your deliverability degrades over weeks before anyone connects the dots. Bounce rates creep up on one provider, but the team responsible uses a different one and doesn't see it.

Bounce House watches for these problems and surfaces them as events. When your domain health score drops, bounces spike, a DNS record changes, or a webhook delivery fails, you get an event you can query, filter, and act on. Critical events become alerts that require acknowledgement, so your team can track who investigated what. You can subscribe webhook endpoints to specific event types with domain and tag filtering, so alerts reach the right people and systems automatically.

Query events

curl "https://api.bouncehouse.cloud/api/accounts/me/events?event_type=health_score_changed&limit=50" \
  -H "Authorization: Bearer bh_your_key"

Returns [{id, event_type, payload, created_at}, ...]

Parameters:

• event_type — filter to a specific type
• since — ISO timestamp
• limit — max 200, default 50

Discover available event types:

curl https://api.bouncehouse.cloud/api/accounts/me/events/types \
  -H "Authorization: Bearer bh_your_key"

Alerts

Alerts are events that require attention. Query and acknowledge them:

# Get unacknowledged alerts
curl "https://api.bouncehouse.cloud/api/accounts/me/alerts?acknowledged=false" \
  -H "Authorization: Bearer bh_your_key"

# Acknowledge an alert
curl -X POST https://api.bouncehouse.cloud/api/accounts/me/alerts/{event_id}/acknowledge \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"acknowledged_by": "ops@example.com", "note": "Investigated — false positive"}'

# Unacknowledge
curl -X DELETE https://api.bouncehouse.cloud/api/accounts/me/alerts/{event_id}/acknowledge \
  -H "Authorization: Bearer bh_your_key"

Event subscriptions

Push events to your own endpoints:

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/event-subscriptions \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/bouncehouse",
    "event_types": ["health_score_changed", "bounce_spike"],
    "domain_filter": "example.com",
    "tag_filter": "abuse",
    "signing_secret": "<your-signing-key>"
  }'

Fields:

• url — your webhook endpoint
• event_types — list of types to subscribe to (omit for all events)
• domain_filter — only events for this domain
• tag_filter — only events for this tag
• signing_secret — we sign payloads with this (encrypted at rest)

Test a subscription:

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/event-subscriptions/{id}/test \
  -H "Authorization: Bearer bh_your_key"

Returns {status, status_code}.

Delivery tracking

Track webhook delivery status and retry failures:

# List deliveries
curl "https://api.bouncehouse.cloud/api/accounts/me/deliveries?status=failed" \
  -H "Authorization: Bearer bh_your_key"

# Manually retry a failed delivery
curl -X POST https://api.bouncehouse.cloud/api/accounts/me/deliveries/{id}/retry \
  -H "Authorization: Bearer bh_your_key"

Delivery status: pending, delivered, failed, retrying. Each delivery tracks attempts, max_attempts, last_status_code, last_error, and next_retry_at.