Invoice Events

Beta

Invoice events are sent when invoice state changes. Subscribe to these events to keep your application in sync.

Event Types

invoice.created

Sent when a new invoice is created.

{
  "event": "invoice.created",
  "data": {
    "id": "inv_01HXYZ123ABC",
    "number": "INV-2025-0001",
    "customer_name": "Acme Ltd",
    "amount": 120.0,
    "currency": "EUR",
    "status": "draft",
    "created_at": "2025-11-24T10:00:00Z"
  },
  "timestamp": "2025-11-24T10:00:00Z"
}

invoice.sent

Sent when an invoice is sent to the customer.

{
  "event": "invoice.sent",
  "data": {
    "id": "inv_01HXYZ123ABC",
    "number": "INV-2025-0001",
    "status": "sent",
    "updated_at": "2025-11-24T10:05:00Z"
  },
  "timestamp": "2025-11-24T10:05:00Z"
}

invoice.paid

Sent when an invoice is marked as paid.

{
  "event": "invoice.paid",
  "data": {
    "id": "inv_01HXYZ123ABC",
    "number": "INV-2025-0001",
    "status": "paid",
    "paid_at": "2025-11-25T10:00:00Z",
    "updated_at": "2025-11-25T10:00:00Z"
  },
  "timestamp": "2025-11-25T10:00:00Z"
}

invoice.overdue

Sent when an invoice becomes overdue.

{
  "event": "invoice.overdue",
  "data": {
    "id": "inv_01HXYZ123ABC",
    "number": "INV-2025-0001",
    "status": "overdue",
    "due_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-02T10:00:00Z"
  },
  "timestamp": "2025-12-02T10:00:00Z"
}

Event Payload Structure

All invoice events include:

event: Event type (e.g., "invoice.created")
data: Invoice data (subset of full invoice object)
timestamp: When the event occurred (ISO 8601 UTC)

Signature Verification

Verify webhook signatures to ensure authenticity:

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
  expected_signature = hmac.new(
      secret.encode(),
      payload.encode(),
      hashlib.sha256
  ).hexdigest()
  return hmac.compare_digest(expected_signature, signature)