Payment and Interaction Webhook Event Types

The primitive.events module defines the full catalog of X-Webhook-Event header values and the typed TypedDict shapes for payment.* and interaction.* webhook bodies. For dispatching on these events end to end, see Handling Webhook Events; for the general contract (signature verification, header discriminator, forward compatibility) see Webhook Events Overview.

Every webhook delivery carries its event name in the X-Webhook-Event HEADER, not in the body. The stored body is sent verbatim with no envelope:

• an email.* body carries event
• a payment.* body carries the name in type
• an interaction.* body is just {"interaction": {...}} with no event/type field at all

Because of that, the header is the only reliable discriminator across all three families, which is why handle_webhook_event keys on it.

Event type catalog#

WEBHOOK_EVENT_TYPES is a tuple[str, ...] containing every current catalog value. It is assembled from three grouped tuples, each also exported:

from primitive.events import (
    EMAIL_EVENT_TYPES,
    PAYMENT_EVENT_TYPES,
    INTERACTION_EVENT_TYPES,
    WEBHOOK_EVENT_TYPES,
)

WEBHOOK_EVENT_TYPES is the concatenation of all three, in that order. WebhookEventType is a plain str alias for "any current catalog value."

is_known_webhook_event_type#

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

Returns True if event_type is a value currently present in WEBHOOK_EVENT_TYPES. Returns False for None and for any value outside the catalog, including future event types your installed SDK version predates.

from primitive.events import is_known_webhook_event_type

is_known_webhook_event_type("payment.settled")       # True
is_known_webhook_event_type("interaction.ack.acked")  # True
is_known_webhook_event_type("payment.refunded")       # False (not yet in the catalog)

PaymentEvent#

A payment.* webhook body. total=False, so every key is optional at the type level; the fields actually present depend on which subtype (PaymentSettledEvent or PaymentFailedEvent) you're looking at.

The stored payload is flat: no envelope, no nested payment object. It carries the event name in type, and the SDK's parser overlays a canonical event key (mirrored from the X-Webhook-Event header) so consumers can branch on a single field.

Fields are marked ReadOnly (PEP 705) so that a subclass can narrow the Literal type without a type-checker error, a mutable TypedDict field is invariant and cannot be narrowed in a subclass otherwise.

PaymentSettledEvent#

A payment.settled webhook event. Subclasses PaymentEvent and narrows event and type to Literal["payment.settled"], so a type checker rejects treating it as a failed event once a guard has narrowed to it.

PaymentFailedEvent#

A payment.failed webhook event. Subclasses PaymentEvent and narrows event and type to Literal["payment.failed"].

InteractionEvent#

An interaction.* webhook body, covering the interaction.x402.* and interaction.ack.* families. The stored payload is just {"interaction": {...}} with no event/type field; the SDK's parser overlays a canonical event key from the header.

InteractionX402Event is an alias for InteractionEvent, exported for callers who want a name that matches the interaction.x402.* subset specifically. There is no separate TypedDict shape for it; the alias is purely for readability at call sites.

Type guards#

Each guard is a TypeGuard predicate over object, so it narrows an already-parsed event value (for example, the return of handle_webhook_event) without requiring a prior isinstance check.

All four accept a plain dict or any object exposing an .event attribute; internally they read via event.get("event") for dicts and getattr(event, "event", None) otherwise, returning None (and hence False) for anything that isn't a string.

from primitive import handle_webhook_event
from primitive.events import is_payment_settled_event, is_interaction_x402_event

event = handle_webhook_event(
    body=raw_body,
    headers=request.headers,
    secret=os.environ["PRIMITIVE_WEBHOOK_SECRET"],
)

if is_payment_settled_event(event):
    # event["amount"] is in token base units
    print(event["challenge_id"], event["amount"], event["settle_tx"])
elif is_interaction_x402_event(event):
    print(event["event"], event["interaction"])

Next steps#