Event Types & Filtering

Zyphr supports 25 webhook event types organized into three categories. Events use a dot-notation format: {resource}.{action}.

Event Categories

Email Events (10 types)

Event Type	Description
email.queued	An email message has been accepted and queued for sending
email.sent	An email message has been sent to the mail provider
email.delivered	An email message was successfully delivered to the recipient
email.bounced	An email message permanently bounced and could not be delivered
email.soft_bounced	An email message temporarily bounced (transient failure)
email.complained	A recipient marked the email as spam
email.opened	A recipient opened the email (tracking pixel loaded)
email.clicked	A recipient clicked a tracked link in the email
email.failed	An email message could not be sent due to a processing error
email.received	An inbound email was received at your domain (see Inbound Email)

Push Events (4 types)

Event Type	Description
push.sent	A push notification has been sent to the provider
push.delivered	A push notification was delivered to the device
push.failed	A push notification could not be delivered
push.expired	A push notification expired before it could be delivered

Auth Events (12 types)

Event Type	Description
user.created	A new end user has been created in an auth application
user.login	An end user has logged in
user.logout	An end user has logged out
user.password_changed	An end user's password has been changed
user.password_reset_requested	An end user requested a password reset
user.email_verified	An end user's email address has been verified
user.phone_verified	An end user's phone number has been verified
user.deleted	An end user has been deleted from an auth application
user.session_revoked	An end user's session has been revoked
user.mfa_enabled	An end user has enabled multi-factor authentication
user.mfa_disabled	An end user has disabled multi-factor authentication
user.impersonated	An admin has started impersonating an end user

Domain Events (2 types)

Event Type	Description
domain.verified	A sending domain has finished verification — all DNS records (verification TXT, SPF, DMARC, DKIM) were observed and SES accepted the identity. Fires on the transition to verified, not on every verifier poll of an already-verified domain.
domain.verification_failed	A sending domain transitioned to the failed verification state — typically because required DNS records weren't detected after the retry window. The customer should re-check their DNS provider and trigger another verification.

Subscribe with events: ['domain.verified'], events: ['domain.*'], or include alongside other categories. Pairs with the Domains MCP tools and the zyphr.domains.* SDK methods so an AI agent can subscribe to terminal status instead of polling GET /v1/domains/{id}.

Event Envelope Format

All webhook payloads use the canonical WebhookEventEnvelope format (API version 2026-02-01):

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "email.delivered",
  "api_version": "2026-02-01",
  "created_at": "2026-02-07T12:00:00.000Z",
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipient_email": "user@example.com",
    "timestamp": "2026-02-07T12:00:00.000Z"
  }
}

Field	Type	Description
id	string	Unique event ID in evt_{uuid} format
type	string	Dot-delimited event type
api_version	string	API version that produced this payload
created_at	string	ISO 8601 timestamp with timezone
data	object	Event-specific payload data

Email Event Data Fields

Field	Type	Description
message_id	string	Zyphr message ID
recipient_email	string | null	Recipient email address
timestamp	string	ISO 8601 timestamp of the event
bounce_type	string | null	Bounce classification — Permanent or Transient (bounce events only)
bounce_subtype	string | null	Detailed bounce sub-type from provider (bounce events only)
complaint_feedback_type	string | null	Complaint feedback type from provider (complaint events only)

Push Event Data Fields

Field	Type	Description
push_message_id	string	Zyphr push message ID
provider	string | null	Push provider — fcm, apns, or webpush
timestamp	string	ISO 8601 timestamp of the event
error_code	string | null	Provider-specific error code (failure events only)
error_message	string | null	Human-readable error description (failure events only)

Auth Event Data Fields

Field	Type	Description
application_id	string	Auth application ID
user	object	User object with id and email
metadata	object	Additional context (provider, IP address, session ID, MFA method, etc.)

Domain Event Data Fields

Field	Type	Description
id	string	Domain ID
domain	string	The sending domain (e.g. sprint.example.com)
status	string	New status: verified or failed
records_verified	number	Count of DNS records verified at the time of the event
records_total	number	Total DNS records required for full verification
verified_at	string | null	ISO 8601 timestamp when verification reached terminal status (null on failure)

Event Filtering

When creating a webhook, specify which events to receive via the events array:

curl -X POST https://api.zyphr.dev/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks",
    "events": ["email.delivered", "email.bounced", "user.created"]
  }'

At least one event type is required. You can update the subscribed events at any time with a PUT request.

Listing Available Event Types

Use the events endpoint to retrieve all available event types with their full registry information:

curl https://api.zyphr.dev/v1/webhooks/events \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by category with the category query parameter:

curl "https://api.zyphr.dev/v1/webhooks/events?category=email" \
  -H "Authorization: Bearer YOUR_API_KEY"

Valid categories: email, push, auth.

The response includes the full event registry with payload field schemas and example payloads for each event type.