Alias Events#

CasaPay sends webhook events for alias-based invoicing activities. Subscribe to these events to track alias creation, invoice processing, and payment completion.

Event types#

Event	Description
`email_alias.created`	A new email alias was created
`email_alias.updated`	An alias was updated (e.g., status change)
`email_alias.disabled`	An alias was disabled
`alias_invoice.received`	A PDF was sent to an alias and received by CasaPay
`alias_invoice.processing`	PDF processing has started
`alias_invoice.processed`	PDF successfully processed, payment request sent to tenant
`alias_invoice.failed`	PDF processing failed
`alias_invoice.paid`	Tenant completed payment on an alias invoice

email_alias.created#

Triggered when a new email alias is created via the API or Chrome Extension.

{
  "id": "evt_alias_created_001",
  "object": "event",
  "type": "email_alias.created",
  "data": {
    "object": {
      "id": "alias_abc123",
      "object": "email_alias",
      "email": "jane.doe@casapay.me",
      "tenant": "cus_123456789",
      "entity": "ent_456def",
      "status": "active",
      "created": 1708732800
    }
  },
  "created": 1708732800,
  "livemode": true
}

alias_invoice.received#

Triggered when a PDF invoice email arrives at an alias address. At this point, processing has not yet started.

{
  "id": "evt_ainv_received_001",
  "object": "event",
  "type": "alias_invoice.received",
  "data": {
    "object": {
      "id": "ainv_abc123",
      "object": "alias_invoice",
      "email_alias": "alias_def456",
      "alias_email": "jane.doe@casapay.me",
      "tenant": "cus_123456789",
      "status": "received",
      "sender_email": "billing@property-manager.com",
      "subject": "Invoice #INV-2025-001",
      "received_at": 1706745500
    }
  },
  "created": 1706745500,
  "livemode": true
}

alias_invoice.processed#

Triggered when PDF processing completes successfully and the payment request has been sent to the tenant.

{
  "id": "evt_ainv_processed_001",
  "object": "event",
  "type": "alias_invoice.processed",
  "data": {
    "object": {
      "id": "ainv_abc123",
      "object": "alias_invoice",
      "email_alias": "alias_def456",
      "alias_email": "jane.doe@casapay.me",
      "tenant": "cus_123456789",
      "status": "processed",
      "extracted_data": {
        "total_amount": 125000,
        "currency": "eur",
        "due_date": "2025-02-01",
        "reference": "INV-2025-001",
        "confidence_score": 0.95
      },
      "payment_request": {
        "id": "pr_xyz789",
        "payment_link": "https://pay.casapay.com/pr_xyz789",
        "amount": 125000,
        "currency": "eur",
        "status": "sent"
      },
      "processed_at": 1706745600
    }
  },
  "created": 1706745600,
  "livemode": true
}

alias_invoice.failed#

Triggered when PDF processing fails. Check the error object for details.

{
  "id": "evt_ainv_failed_001",
  "object": "event",
  "type": "alias_invoice.failed",
  "data": {
    "object": {
      "id": "ainv_def456",
      "object": "alias_invoice",
      "email_alias": "alias_def456",
      "status": "failed",
      "error": {
        "code": "pdf_unreadable",
        "message": "The attached PDF could not be parsed. Please ensure the file is a valid PDF document.",
        "type": "processing_error"
      }
    }
  },
  "created": 1706745700,
  "livemode": true
}

Error codes#

Code	Description
`pdf_unreadable`	PDF file could not be opened or parsed
`no_attachment`	Email did not contain a PDF attachment
`amount_not_found`	Could not extract invoice amount from PDF
`multiple_attachments`	Multiple PDFs attached; only one is supported per email
`alias_paused`	The alias is currently paused
`alias_disabled`	The alias has been disabled
`low_confidence`	Extraction confidence below threshold; flagged for review

alias_invoice.paid#

Triggered when the tenant completes payment on an alias invoice.

{
  "id": "evt_ainv_paid_001",
  "object": "event",
  "type": "alias_invoice.paid",
  "data": {
    "object": {
      "id": "ainv_abc123",
      "object": "alias_invoice",
      "status": "paid",
      "payment_intent": "pi_completed789",
      "extracted_data": {
        "total_amount": 125000,
        "currency": "eur",
        "reference": "INV-2025-001"
      },
      "paid_at": 1706832000
    }
  },
  "created": 1706832000,
  "livemode": true
}