Webhook Events
Complete catalog of webhook events and their payloads
Wicket sends webhooks for various events across People, Organizations, and Roles. This page documents all available event types and their payload structures.
Event Catalog
People Events
people.changed
Fired when a person record is created or updated.
Example Payload:
{
"id": "a5b33199-9dd3-4552-8c47-028f6c32ef48",
"type": "person_webhook_summary",
"event_type": "people.changed",
"event_id": "6d2b7371-36b9-4060-b6ca-ddafda50541d",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"uuid": "a5b33199-9dd3-4552-8c47-028f6c32ef48",
"given_name": "John",
"family_name": "Smith",
"primary_email_address": "john@mail.com",
"updated_at": "2023-06-21T16:53:43.600Z"
},
"meta": {
"action": "updated",
"changes": {
"attributes": [
"given_name"
],
"internal_fields": false
}
}
}Use Cases:
- Sync person profiles to external systems
- Update CRM records
- Trigger welcome emails for new people
- Track profile changes
people.email_changed
Fired when an email address is added, updated, or removed for a person.
Example Payload:
{
"id": "e7f180d7-9830-494c-8e5e-eb864dcf29dc",
"type": "email_changed_webhook_summary",
"event_type": "people.email_changed",
"event_id": "6d2b7371-36b9-4060-b6ca-ddafda50541d",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"uuid": "e7f180d7-9830-494c-8e5e-eb864dcf29dc",
"address": "newemail@example.com",
"address_was": "oldemail@example.com",
"primary": true,
"primary_changed": true,
"primary_was": false,
"updated_at": "2023-06-21T16:53:43.600Z"
},
"relationships": {
"emailable": {
"data": {
"id": "a5b33199-9dd3-4552-8c47-028f6c32ef48",
"type": "people"
}
}
},
"meta": {
"action": "updated",
"changes": {
"attributes": [
"localpart",
"address"
],
"internal_fields": false
}
}
}Key Attributes:
address: Current email addressaddress_was: Previous email (if changed)primary: Whether this is the primary emailprimary_changed: Whether primary status changedprimary_was: Previous primary status
Use Cases:
- Update email marketing lists
- Sync email changes to external systems
- Detect primary email changes
- Track email history
people.phone_changed
Fired when a phone number is added, updated, or removed for a person.
Example Payload:
{
"id": "phone-uuid",
"type": "phone_changed_webhook_summary",
"event_type": "people.phone_changed",
"event_id": "event-uuid",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"uuid": "phone-uuid",
"number": "+16133556666",
"number_was": "+16133556664",
"primary": true,
"primary_changed": true,
"primary_was": false,
"updated_at": "2023-06-21T16:53:43.600Z"
},
"relationships": {
"phoneable": {
"data": {
"id": "person-uuid",
"type": "people"
}
}
},
"meta": {
"action": "created",
"changes": {
"attributes": [
"uuid",
"number",
"type",
"phoneable",
"primary"
],
"internal_fields": true
}
}
}Use Cases:
- Update contact information in external systems
- Send SMS verification for phone changes
- Sync phone numbers to communication platforms
people.address_changed
Fired when a physical address is added, updated, or removed for a person.
Example Payload:
{
"id": "address-uuid",
"type": "address_changed_webhook_summary",
"event_type": "people.address_changed",
"event_id": "event-uuid",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"uuid": "address-uuid",
"address1": "123 Wicket Lane",
"address2": "Suite 100",
"city": "Ottawa",
"zip_code": "K1Z 6X6",
"state_name": "ON",
"country_code": "CA",
"primary": true,
"primary_changed": true,
"updated_at": "2023-06-21T16:53:43.600Z"
},
"relationships": {
"addressable": {
"data": {
"id": "person-uuid",
"type": "people"
}
}
},
"meta": {
"action": "created",
"changes": {
"attributes": [
"uuid",
"type",
"company_name",
"city",
"zip_code",
"address1",
"address2",
"state_name",
"country_code",
"primary",
"addressable",
"department",
"division"
],
"internal_fields": true
}
}
}Use Cases:
- Update mailing addresses in shipping systems
- Sync address changes to CRM
- Trigger address verification workflows
people.web_address_changed
Fired when a web address (website, social media profile) is added, updated, or removed for a person.
Example Payload:
{
"id": "web-address-uuid",
"type": "web_address_changed_webhook_summary",
"event_type": "people.web_address_changed",
"event_id": "event-uuid",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"uuid": "web-address-uuid",
"url": "https://linkedin.com/in/johnsmith",
"url_was": "https://linkedin.com/in/jsmith",
"web_address_type": "linkedin",
"primary": false,
"primary_changed": false,
"updated_at": "2023-06-21T16:53:43.600Z"
},
"relationships": {
"web_addressable": {
"data": {
"id": "person-uuid",
"type": "people"
}
}
},
"meta": {
"action": "created",
"changes": {
"attributes": [
"uuid",
"type",
"web_addressable",
"address"
],
"internal_fields": true
}
}
}Use Cases:
- Sync social media profiles
- Update website links
- Track online presence changes
Organization Events
organizations.changed
Fired when an organization record is created or updated.
Example Payload:
{
"id": "org-uuid",
"type": "organization_webhook_summary",
"event_type": "organizations.changed",
"event_id": "event-uuid",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"uuid": "org-uuid",
"legal_name": "ACME Corporation",
"alternate_name": "ACME Corp",
"updated_at": "2023-06-21T16:53:43.600Z"
},
"meta": {
"action": "updated",
"changes": {
"attributes": [
"alternate_name_en",
"legal_name_en"
],
"internal_fields": false
}
}
}Use Cases:
- Sync organization data to CRM
- Update company directories
- Track organizational changes
organizations.email_changed
Fired when an email address is added, updated, or removed for an organization.
Payload Structure: Similar to people.email_changed, but with emailable.type: "organizations"
organizations.phone_changed
Fired when a phone number is added, updated, or removed for an organization.
Payload Structure: Similar to people.phone_changed, but with phoneable.type: "organizations"
organizations.address_changed
Fired when a physical address is added, updated, or removed for an organization.
Payload Structure: Similar to people.address_changed, but with addressable.type: "organizations"
organizations.web_address_changed
Fired when a web address is added, updated, or removed for an organization.
Payload Structure: Similar to people.web_address_changed, but with web_addressable.type: "organizations"
Role Events
roles.granted
Fired when a role is assigned to a user.
Example Payload:
{
"id": "role-assignment-uuid",
"type": "role_granted_webhook_summary",
"event_type": "roles.granted",
"event_id": "event-uuid",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"role_name": "member",
"person_uuid": "person-uuid",
"granted_at": "2023-06-21T16:53:43.600Z"
}
}Use Cases:
- Sync permissions to external systems
- Trigger access provisioning workflows
- Audit role assignments
roles.revoked
Fired when a role is removed from a user.
Example Payload:
{
"id": "role-revocation-uuid",
"type": "role_revoked_webhook_summary",
"event_type": "roles.revoked",
"event_id": "event-uuid",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"role_name": "member",
"person_uuid": "person-uuid",
"revoked_at": "2023-06-21T16:53:43.600Z"
}
}Use Cases:
- Revoke access in external systems
- Trigger deprovisioning workflows
- Audit role removals
Event Metadata
Event payloads include a meta object with additional context:
action: either "created" or "updated"changes: an object with:attributes: array of API field names that changed (e.g. ["given_name", "family_name"])internal_fields: boolean; true if non-API database fields also changed, useful for handling edge cases where a change occurred but no exposed attributes were affecteddata_field_schema_slugs: (present when attributes includes data_fields) array of schema slugs identifying which additional info schemas changed
You can filter on any of these fields. For edge cases and advanced filter combinations, use the webhook preview endpoint to test your filters before deploying.
Event Bundling
Multiple events may be bundled together in a single webhook delivery when they occur simultaneously:
{
"webhook_delivery_timestamp": "2023-06-20T18:10:20.183Z",
"webhook_bundle_uuid": "bundle-uuid",
"events": [
{
"event_type": "people.changed",
// ... event 1 data
},
{
"event_type": "people.email_changed",
// ... event 2 data
},
{
"event_type": "people.phone_changed",
// ... event 3 data
}
],
"test": false
}Why events are bundled:
- A person record is updated along with their email and phone
- Multiple addresses are updated in a single API call
- Batch operations trigger multiple events simultaneously
Handling Events
Basic Event Handler
app.post('/webhooks/wicket', (req, res) => {
const payload = req.body;
// Acknowledge receipt immediately
res.status(200).send('OK');
// Process events asynchronously
processEvents(payload.events);
});
function processEvents(events) {
for (const event of events) {
switch (event.event_type) {
case 'people.changed':
handlePersonChanged(event);
break;
case 'people.email_changed':
handleEmailChanged(event);
break;
case 'people.phone_changed':
handlePhoneChanged(event);
break;
case 'organizations.changed':
handleOrganizationChanged(event);
break;
case 'roles.granted':
handleRoleGranted(event);
break;
case 'roles.revoked':
handleRoleRevoked(event);
break;
default:
console.warn('Unknown event type:', event.event_type);
}
}
}Tracking Changes
Many events include *_was fields to track what changed:
function handleEmailChanged(event) {
const { address, address_was, primary_changed } = event.attributes;
if (address_was) {
console.log(`Email changed from ${address_was} to ${address}`);
} else {
console.log(`New email added: ${address}`);
}
if (primary_changed) {
console.log(`Primary status changed to: ${event.attributes.primary}`);
}
}Event Deduplication
Use event_id to prevent duplicate processing:
const processedEventIds = new Set();
function processEvents(events) {
for (const event of events) {
if (processedEventIds.has(event.event_id)) {
console.log('Skipping duplicate event:', event.event_id);
continue;
}
processEvent(event);
processedEventIds.add(event.event_id);
}
}Common Patterns
Syncing to External Systems
async function handlePersonChanged(event) {
const personUuid = event.attributes.uuid;
// Fetch full person record from API
const person = await fetchPerson(personUuid);
// Sync to external CRM
await updateCRM(person);
}Triggering Workflows
async function handleRoleGranted(event) {
const { role_name, person_uuid } = event.attributes;
if (role_name === 'member') {
// Send welcome email
await sendWelcomeEmail(person_uuid);
// Provision access
await provisionAccess(person_uuid);
// Add to mailing list
await addToMailingList(person_uuid);
}
}Audit Logging
async function logEvent(event) {
await db.audit_log.insert({
event_id: event.event_id,
event_type: event.event_type,
event_timestamp: event.event_timestamp,
resource_id: event.id,
resource_type: event.type,
attributes: event.attributes,
processed_at: new Date()
});
}Best Practices
- Process events asynchronously: Respond with 200 immediately, then process events in background
- Use event IDs for deduplication: Prevent processing the same event multiple times
- Handle all subscribed events: Log warnings for unexpected event types
- Track changes with
*_wasfields: Use these to understand what changed - Fetch full records when needed: Webhook payloads contain summaries; fetch full data from API if needed
- Implement retry logic: If your processing fails, retry with exponential backoff
- Monitor event processing: Track success/failure rates and processing times