Skip to main content
Functions for receiving what Deutero POSTs to you: organization events (secret from client.webhooks.create()) and interview-flow signals (per-step secret from client.graph.get_signals()). The module makes no API calls. See Receiving webhooks for a full receiver. payload arguments accept bytes, bytearray or str, and should be the raw request body exactly as received. headers can be any mapping; lookup is case-insensitive.

​
unwrap()

Verify a delivery and parse it into an event. This is the function most receivers need.
​
bytes | bytearray | str
required
The raw request body.
​
Mapping[str, str]
required
The request headers.
​
str
required
The whsec_... signing secret for the endpoint or signal step.
​
int | None
default:"300"
The maximum age and clock skew of webhook-timestamp, in seconds. None disables the check, for example when replaying stored deliveries.
Returns a typed event such as InterviewCompletedEvent for known organization events, or a plain WebhookEvent for signals and unrecognized types. Raises WebhookVerificationError if the delivery isn’t authentic or isn’t an event.

​
verify()

Check a delivery’s signature and timestamp without parsing it. Takes the same arguments as unwrap(). Raises WebhookVerificationError if headers are missing, the timestamp is outside the tolerance, or no signature matches.

​
parse_event()

Parse a delivery into an event without verifying it. Use it only on payloads you’ve already verified, or in tests. Raises WebhookVerificationError if the body isn’t a JSON event envelope.

​
sign()

Build the signature headers Deutero would send with payload, for testing your receiver locally.
​
bytes | bytearray | str
required
The body to sign.
​
str
required
The whsec_... signing secret.
​
str
required
The message ID, sent as webhook-id.
​
int
Unix time to sign with. Defaults to now.
Returns a dict of headers: webhook-id, webhook-timestamp and webhook-signature.

​
Constants

​
Event models

​
WebhookEvent

The base class for every event, and the type returned for signals and unknown event types.
​
str
The event type, such as interview.completed. For signals, the step’s signal type.
​
datetime | None
When the event happened.
​
Any
The event payload. A typed model on the subclasses below, otherwise a dict.
​
str | None
The webhook-id header. Unique per message, so use it to deduplicate retries.
​
bool
True when the X-Deutero-Simulated header is set, meaning a signal from a simulated interview.

​
Typed events

All data fields are optional strings, except completed, which is an optional bool. survey_id is the study ID under its older name. participant_id is Deutero’s own ID for the participant. external_participant_id and web_source come from the participant’s link and aren’t authenticated. If a known event type arrives with data that no longer fits its model, unwrap still returns it, as a plain WebhookEvent.