Payload Reference

Every Aura webhook ships in the same envelope. The data object's shape depends on the event type. This page documents each shape exactly as it appears in production.

The interfaces below mirror apps/api/src/lib/webhook-events.ts — the canonical source of truth. Fields here that show string | null may arrive as null if the underlying data is missing.

Envelope

interface WebhookPayload<T> {
  event: WebhookEventType;     // e.g. "call.booked"
  created_at: string;          // ISO 8601, UTC
  organization_id: string;     // The org the event belongs to
  data: T;                     // Resource payload — see below
}

Field	Type	Notes
`event`	`string`	One of the 14 event types
`created_at`	`string`	ISO 8601 timestamp of emission, UTC
`organization_id`	`string`	Your Aura organization ID
`data`	`object`	Shape depends on `event`

`LeadWebhookData`

Emitted on lead.created, lead.updated, lead.status_changed.

Field	Type	Description
`id`	`string`	Lead ID
`name`	`string \| null`	Full name, if provided
`email`	`string \| null`	Email, if provided
`phone`	`string \| null`	Phone, if provided
`company`	`string \| null`	Company, if provided
`status`	`string`	Pipeline stage (see status values below)
`timezone`	`string \| null`	IANA timezone, if known
`source`	`object \| null`	Attribution — see below
`created_at`	`string`	When the lead was created (ISO 8601)
`updated_at`	`string`	When the lead was last updated (ISO 8601)

`source` object

Field	Type	Description
`utm_source`	`string \| null`	Traffic platform (e.g. `google`, `facebook`)
`utm_medium`	`string \| null`	Channel type (e.g. `cpc`, `email`, `social`)
`utm_campaign`	`string \| null`	Campaign name
`utm_term`	`string \| null`	Paid search keywords / targeting criteria
`utm_content`	`string \| null`	Ad creative or A/B variant
`referrer`	`string \| null`	HTTP referrer — embed host page or traffic source

Lead `status` values

Value	Meaning
`interested`	Contact info captured, no booking yet
`qualified`	Form questions answered, fit confirmed
`scheduled`	Call booked, in the future
`attended`	Call completed
`closed`	Deal won
`lost`	Deal lost
`canceled`	Booking canceled
`disqualified`	Marked as not a fit

`CallWebhookData`

Emitted on call.booked, call.updated, call.started, call.completed, call.canceled, call.rescheduled, call.no_show.

Field	Type	Description
`id`	`string`	Call ID
`lead_id`	`string`	Associated lead ID
`closer_id`	`string \| null`	Assigned host's user ID
`booking_link_id`	`string \| null`	Which funnel / product the call came through
`scheduled_at`	`string`	Scheduled meeting time (ISO 8601)
`duration`	`number \| null`	Scheduled duration in minutes
`status`	`string \| null`	Call status (`scheduled`, `attended`, `no_show`, `canceled`, etc.)
`conferencing_url`	`string \| null`	Video conference URL
`utm_source`	`string \| null`	Attribution: traffic platform
`utm_medium`	`string \| null`	Attribution: channel type
`utm_campaign`	`string \| null`	Attribution: campaign name
`utm_term`	`string \| null`	Attribution: paid search keywords
`utm_content`	`string \| null`	Attribution: ad creative or A/B variant
`referral`	`string \| null`	Partner / affiliate identifier (separate from `utm_source`)
`guest_rsvp_status`	`string \| null`	Guest's calendar RSVP (`yes`, `no`, `maybe`, `noreply`)
`guest_rsvp_confirmed_at`	`string \| null`	When the guest first RSVP'd `yes`
`created_at`	`string`	When the call was created
`updated_at`	`string`	When the call was last updated

Call attribution fields are flat on the call payload (utm_source etc.), whereas lead attribution is nested under source. This intentional asymmetry mirrors the underlying schema: calls inherit UTM at booking time from the originating lead, but are stored as columns for fast pipeline filtering.

`CallCloserReassignedWebhookData`

Emitted on call.closer_reassigned. This is the only call event with a non-CallWebhookData shape — it carries the swap details rather than the full call record.

Field	Type	Description
`call_id`	`string`	Affected call ID
`previous_closer_id`	`string \| null`	The host being unassigned
`previous_closer_name`	`string`	Cached display name of the previous host
`new_closer_id`	`string`	The host being assigned
`new_closer_name`	`string`	Cached display name of the new host
`scheduled_at`	`string`	Call's scheduled time (unchanged by reassignment)
`conferencing_link`	`string \| null`	Conferencing URL on the new event
`new_event_id`	`string`	The canonical Nylas event ID after the swap
`booking_link_id`	`string \| null`	Originating booking link
`reassigned_by_user_id`	`string`	Admin or Partner API caller who performed the swap
`old_event_orphaned`	`boolean`	`true` if the old event could not be cleanly canceled on the previous host's calendar

`PaymentWebhookData`

Emitted on payment.succeeded, payment.failed, payment.refunded.

Field	Type	Description
`id`	`string`	Payment ID
`lead_id`	`string \| null`	Associated lead, if known
`call_id`	`string \| null`	Associated call, if the payment is tied to a deal
`amount`	`number`	Amount in the currency's smallest unit (e.g. cents for USD)
`currency`	`string`	ISO 4217 lowercase (`usd`, `eur`, etc.)
`status`	`string`	Stripe-style status (`succeeded`, `failed`, `refunded`)
`payment_date`	`string`	When the payment was processed (ISO 8601)
`created_at`	`string`	When the payment record was created

Conventions

Timestamps

All timestamps are ISO 8601 UTC (Z suffix):

2026-05-12T14:30:00.000Z

Null handling

Optional fields are emitted as null rather than omitted. Always treat the contract as nullable for any field marked string | null here:

const phone = data.phone ?? "(not provided)";

Forward compatibility

Aura may add new fields to any payload without a major version bump. Consumers must ignore unknown fields. Removing or renaming a documented field is a breaking change and will trigger a schema-diff review on our side before shipping.

Verifying signatures

Webhook deliveries carry a signed header X-Aura-Signature-V1 of the form:

X-Aura-Signature-V1: t=1715520600000,v1=<sha256_hex>[,v1=<previous_sig>]

The signed string is ${timestamp}.${rawBody} — not the body alone — which prevents replay attacks. Reject deliveries whose t differs from your server clock by more than 5 minutes.

During a 24-hour secret rotation window, two v1= segments are present. Accept the delivery if either signature verifies — this lets you rotate secrets with zero downtime.

The legacy bare-hex X-Aura-Signature header is still sent for backwards compatibility but offers no replay protection; new integrations should verify the V1 header only.

Next steps

Event Types — when each event fires
Webhooks Overview — setup, retries, SSRF rules
API Reference — the same data, but pull-based

Payload Reference

On this page