Python SDK Type Reference

Every type on this page is importable from the top-level primitive package unless otherwise noted. Types generated from the webhook JSON Schema (EmailReceivedEvent, EmailAuth, EmailAnalysis, ForwardAnalysis, and friends) are covered in depth on Payment and Interaction Webhook Event Types; this page is the map of everything else: the normalized ReceivedEmail shape and the shared event-type catalog.

ReceivedEmail and its parts#

primitive.receive(...) and primitive.normalize_received_email(...) return a ReceivedEmail dataclass. It is the SDK-normalized representation of an inbound email; see Receiving and Parsing Inbound Email for the full receive flow and field-by-field usage. This page documents only the dataclass shapes.

@dataclass(frozen=True)
class ReceivedEmail:
    id: str
    event_id: str
    received_at: str
    sender: ReceivedEmailAddress
    reply_target: ReceivedEmailAddress
    received_by: str
    received_by_all: list[str]
    subject: str | None
    reply_subject: str
    forward_subject: str
    text: str | None
    thread: ReceivedEmailThread
    attachments: list[WebhookAttachment]
    auth: EmailAuth
    analysis: EmailAnalysis
    raw: EmailReceivedEvent

ReceivedEmailAddress#

A single parsed address with an optional display name.

@dataclass(frozen=True)
class ReceivedEmailAddress:
    address: str
    name: str | None = None

ReceivedEmailThread#

Threading headers extracted from the parsed email, used to build reply/forward headers.

@dataclass(frozen=True)
class ReceivedEmailThread:
    message_id: str | None
    in_reply_to: list[str]
    references: list[str]

Helper functions that operate on these types#

Webhook event-type catalog#

These live in primitive.events (also re-exported from the top-level primitive package for the guard functions and WEBHOOK_EVENT_TYPES). Full event-handling flow is documented on Handling Webhook Events; this section is the type catalog reference. See also Payment and Interaction Webhook Event Types for the complete PaymentEvent/InteractionEvent reference.

The event name for every family arrives in the X-Webhook-Event HEADER, never in the body, the stored payload is sent verbatim with no envelope. An email.* body carries event, a payment.* body carries the name in type, and an interaction.* body is just {"interaction": {...}} with no event/type field at all. That's why every catalog and guard function below keys off the header-derived value, not a body field.

Event-type tuples#

WebhookEventType is a plain str type alias for any current catalog value, as carried in the X-Webhook-Event header.

def is_known_webhook_event_type(event_type: str | None) -> bool: ...

Returns True if event_type is a value present in WEBHOOK_EVENT_TYPES.

PaymentEvent and its subtypes#

PaymentEvent is a TypedDict (total=False) representing a payment.* webhook body. The stored payload is flat, no envelope, no nested payment object, and carries the event name in type; the parser overlays a canonical event field (mirrored from the header) so consumers can branch on one field.

PaymentSettledEvent and PaymentFailedEvent are subclasses of PaymentEvent that narrow event/type to their respective literal, using ReadOnly (PEP 705) so a type checker rejects treating one as the other after a guard narrows it:

InteractionEvent#

An interaction.* webhook body (TypedDict, total=False). The stored payload is just {"interaction": {...}} with no event/type field; the parser overlays a canonical event from the header.

InteractionX402Event is a type alias for InteractionEvent, the same shape, named for the interaction.x402.* family specifically.

Type guards#

All guards accept object and narrow via TypeGuard, so they're safe to call on any parsed event value.

from primitive import handle_webhook_event, is_payment_settled_event, is_interaction_x402_event

event = handle_webhook_event(body=raw_body, headers=headers, secret=secret)

if is_payment_settled_event(event):
    print(event["challenge_id"], event["amount"], event["settle_tx"])
elif is_interaction_x402_event(event):
    print(event["event"], event["interaction"])

Next steps#