Webhook Payload Reference

This document provides complete documentation for all webhook payload fields and configurations.

Payload Structure

{
  "event": "string",
  "timestamp": "ISO 8601 string",
  "site_url": "string",
  "user": { ... },
  "woocommerce": { ... },
  "context": { ... },
  "device": { ... }
}

Core Fields (Always Included)

Event Metadata

Field	Type	Description	Example
`event`	string	Event type	`"user_registered"`
`timestamp`	string	ISO 8601 UTC timestamp	`"2024-01-15T10:30:00Z"`
`site_url`	string	WordPress site URL	`"https://yoursite.com"`

User Object

Always included in every webhook:

{
  "user": {
    "id": 123,
    "email": "john.smith@gmail.com",
    "first_name": "John",
    "last_name": "Smith",
    "display_name": "John Smith",
    "username": "johnsmith",
    "role": "customer",
    "locale": "en_US",
    "google_id": "123456789012345678901",
    "avatar_url": "https://lh3.googleusercontent.com/a/...",
    "registered_at": "2024-01-15T10:30:00Z",
    "login_count": 1,
    "ip_address": "192.168.1.1"
  }
}

User Fields

Field	Type	Description
`id`	integer	WordPress user ID
`email`	string	User's email address
`first_name`	string	First name from Google
`last_name`	string	Last name from Google
`display_name`	string	Full display name
`username`	string	WordPress username
`role`	string	WordPress role (customer, subscriber, etc.)
`locale`	string	User's locale setting
`google_id`	string	Google account identifier
`avatar_url`	string	Google profile picture URL
`registered_at`	string	Account creation timestamp
`login_count`	integer	Total Google logins
`ip_address`	string	User's IP (can be anonymized)

Optional Sections

Enable these in webhook settings for additional data.

WooCommerce Data

Enable: Check "Include WooCommerce data"

Availability: Only when WooCommerce is active and user has orders.

{
  "woocommerce": {
    "is_customer": true,
    "order_count": 5,
    "total_spent": "249.95",
    "currency": "USD",
    "last_order_date": "2024-01-10T15:45:00Z",
    "last_order_id": 456,
    "average_order_value": "49.99"
  }
}

WooCommerce Fields

Field	Type	Description
`is_customer`	boolean	Has the Customer role
`order_count`	integer	Total completed orders
`total_spent`	string	Lifetime spend (decimal string)
`currency`	string	Store currency code
`last_order_date`	string	Most recent order timestamp
`last_order_id`	integer	Most recent order ID
`average_order_value`	string	Average order amount

Context Data

Enable: Check "Include context data"

{
  "context": {
    "login_method": "one_tap",
    "page_url": "https://yoursite.com/checkout/",
    "page_type": "checkout",
    "referrer": "https://google.com/",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "summer_sale"
  }
}

Context Fields

Field	Type	Description
`login_method`	string	`"one_tap"` or `"button"`
`page_url`	string	URL where login occurred
`page_type`	string	Page type (checkout, cart, my_account, etc.)
`referrer`	string	HTTP referrer
`utm_source`	string	UTM source parameter
`utm_medium`	string	UTM medium parameter
`utm_campaign`	string	UTM campaign parameter
`utm_term`	string	UTM term parameter
`utm_content`	string	UTM content parameter

Device Data

Enable: Check "Include device data"

{
  "device": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
    "is_mobile": false,
    "platform": "macOS",
    "browser": "Chrome",
    "browser_version": "120.0.0"
  }
}

Device Fields

Field	Type	Description
`user_agent`	string	Full user agent string
`is_mobile`	boolean	Mobile device detection
`platform`	string	Operating system
`browser`	string	Browser name
`browser_version`	string	Browser version

Event-Specific Examples

user_registered Event

Full payload for new user registration:

{
  "event": "user_registered",
  "timestamp": "2024-01-15T10:30:00Z",
  "site_url": "https://yourstore.com",
  "user": {
    "id": 789,
    "email": "newuser@gmail.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "display_name": "Jane Doe",
    "username": "janedoe",
    "role": "customer",
    "locale": "en_US",
    "google_id": "987654321098765432109",
    "avatar_url": "https://lh3.googleusercontent.com/a/...",
    "registered_at": "2024-01-15T10:30:00Z",
    "login_count": 1,
    "ip_address": "203.0.113.42"
  },
  "woocommerce": {
    "is_customer": true,
    "order_count": 0,
    "total_spent": "0.00",
    "currency": "USD",
    "last_order_date": null,
    "last_order_id": null,
    "average_order_value": "0.00"
  },
  "context": {
    "login_method": "one_tap",
    "page_url": "https://yourstore.com/checkout/",
    "page_type": "checkout",
    "referrer": "https://google.com/search?q=...",
    "utm_source": "google",
    "utm_medium": "organic",
    "utm_campaign": null
  },
  "device": {
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)...",
    "is_mobile": true,
    "platform": "iOS",
    "browser": "Safari",
    "browser_version": "17.0"
  }
}

user_logged_in Event

Full payload for returning user:

{
  "event": "user_logged_in",
  "timestamp": "2024-01-20T14:15:00Z",
  "site_url": "https://yourstore.com",
  "user": {
    "id": 789,
    "email": "returning@gmail.com",
    "first_name": "John",
    "last_name": "Smith",
    "display_name": "John Smith",
    "username": "johnsmith",
    "role": "customer",
    "locale": "en_US",
    "google_id": "123456789012345678901",
    "avatar_url": "https://lh3.googleusercontent.com/a/...",
    "registered_at": "2024-01-01T09:00:00Z",
    "login_count": 15,
    "ip_address": "198.51.100.23"
  },
  "woocommerce": {
    "is_customer": true,
    "order_count": 8,
    "total_spent": "542.80",
    "currency": "USD",
    "last_order_date": "2024-01-18T11:30:00Z",
    "last_order_id": 1234,
    "average_order_value": "67.85"
  },
  "context": {
    "login_method": "button",
    "page_url": "https://yourstore.com/my-account/",
    "page_type": "my_account",
    "referrer": "https://yourstore.com/",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null
  },
  "device": {
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "is_mobile": false,
    "platform": "Windows",
    "browser": "Firefox",
    "browser_version": "121.0"
  }
}

HTTP Headers

Headers sent with every webhook:

Header	Description	Example
`Content-Type`	Payload format	`application/json`
`X-OneTap-Event`	Event type	`user_registered`
`X-OneTap-Signature`	HMAC signature	`sha256=abc123...`
`X-OneTap-Delivery`	Unique delivery ID	`550e8400-e29b-...`
`X-OneTap-Timestamp`	Unix timestamp	`1705315800`
`User-Agent`	Client identifier	`OneTap-Webhook/1.0`

Signature Verification

Generate Expected Signature

$payload = file_get_contents('php://input');
$secret = 'your_webhook_secret';
$signature = 'sha256=' . hash_hmac('sha256', $payload, $secret);

Verify Incoming Signature

$received = $_SERVER['HTTP_X_ONETAP_SIGNATURE'];
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    die('Invalid signature');
}

Node.js Example

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

    return crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(signature)
    );
}

Data Types

Type	Format	Example
string	UTF-8	`"John Smith"`
integer	Number	`123`
boolean	true/false	`true`
timestamp	ISO 8601 UTC	`"2024-01-15T10:30:00Z"`
decimal	String	`"99.95"`
null	null	`null`

Privacy Considerations

IP Anonymization

If GDPR settings enabled, IP may be anonymized:

"ip_address": "203.0.113.0"  // Last octet zeroed

Sensitive Data

Email is always included (necessary for identification)
Google ID is pseudonymous (doesn't reveal identity alone)
User agent may contain device details

When processing webhook data:

Store only necessary fields
Implement data retention policies
Honor deletion requests
Document processing purposes

Next Steps

Zapier Integration - Connect to Zapier
Make Integration - Connect to Make
Webhooks Overview - Configuration guide

Payload Structure​

Core Fields (Always Included)​

Event Metadata​

User Object​

User Fields​

Optional Sections​

WooCommerce Data​

WooCommerce Fields​

Context Data​

Context Fields​

Device Data​

Device Fields​

Event-Specific Examples​

user_registered Event​

user_logged_in Event​

HTTP Headers​

Signature Verification​

Generate Expected Signature​

Verify Incoming Signature​

Node.js Example​

Data Types​

Privacy Considerations​

IP Anonymization​

Sensitive Data​

GDPR Compliance​

Next Steps​