Pre-release — content may change.

GuidesWebhooks

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 address
  • address_was: Previous email (if changed)
  • primary: Whether this is the primary email
  • primary_changed: Whether primary status changed
  • primary_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 affected
    • data_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

  1. Process events asynchronously: Respond with 200 immediately, then process events in background
  2. Use event IDs for deduplication: Prevent processing the same event multiple times
  3. Handle all subscribed events: Log warnings for unexpected event types
  4. Track changes with *_was fields: Use these to understand what changed
  5. Fetch full records when needed: Webhook payloads contain summaries; fetch full data from API if needed
  6. Implement retry logic: If your processing fails, retry with exponential backoff
  7. Monitor event processing: Track success/failure rates and processing times

On this page