Skip to main content
Coming Soon - Webhook functionality is currently in development. This page documents the planned implementation.

​
Overview

The contact.updated event is triggered when information about an existing contact is modified. This includes changes to personal details, contact information, tags, subscription status, or any other editable field.

​
When This Event Fires

  • Contact information is updated in the dashboard
  • Email address or phone number is changed
  • Mailing address is added or modified
  • Contact subscribes or unsubscribes from emails
  • Tags are added or removed
  • Custom fields are updated
  • Contact information is updated via the API
This event fires for any field change on the contact record. Check the updated_fields array to see exactly what changed.

​
Webhook Payload

{
  "id": "evt_klm789nop012",
  "type": "contact.updated",
  "created_at": "2024-01-20T15:45:00Z",
  "data": {
    "id": "cont_987654321",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "+1234567890",
    "address": {
      "line1": "456 New St",
      "line2": null,
      "city": "Oakland",
      "state": "CA",
      "postal_code": "94601",
      "country": "US"
    },
    "company": "Acme Corporation",
    "source": "donation",
    "tags": ["donor", "first-time", "monthly-giving"],
    "subscribed": true,
    "updated_fields": ["last_name", "email", "address", "tags"],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T15:45:00Z"
  },
  "account_id": "acct_xyz789"
}

​
Event Data Fields

​
id
string
required
Unique identifier for the contact (prefixed with cont_)
​
first_name
string
required
Contact’s first name
​
last_name
string
required
Contact’s last name
​
email
string
required
Contact’s email address
​
phone
string
Contact’s phone number in E.164 format
​
address
object
Contact’s mailing address
​
company
string
Company or organization name
​
source
string
required
How the contact was originally created: donation, ticket, signup, manual, api, or import
​
tags
array
Array of tags applied to the contact
​
subscribed
boolean
required
Whether the contact is subscribed to email communications
​
updated_fields
array
required
List of field names that were changed (e.g., ["email", "address", "tags"])
​
created_at
string
required
ISO 8601 timestamp when the contact was originally created
​
updated_at
string
required
ISO 8601 timestamp when the contact was last updated

​
Common Use Cases

Keep external systems updated when contact information changes:
async function handleContactUpdated(event) {
  const { id, first_name, last_name, email, phone, address, updated_fields } = event.data;

  // Sync to CRM
  await crm.updateContact(id, {
    firstName: first_name,
    lastName: last_name,
    email: email,
    phone: phone,
    address: address,
    updatedFields: updated_fields
  });
}
Update email lists when contact email addresses change:
async function handleContactUpdated(event) {
  const { email, updated_fields, subscribed } = event.data;

  if (updated_fields.includes('email')) {
    // Update in email platform
    await emailPlatform.updateSubscriber({
      old_email: event.previous_values?.email,
      new_email: email,
      subscribed: subscribed
    });
  }
}
Monitor when contacts opt in or out of communications:
async function handleContactUpdated(event) {
  const { id, email, first_name, subscribed, updated_fields } = event.data;

  if (updated_fields.includes('subscribed')) {
    await analytics.trackEvent(subscribed ? 'subscribed' : 'unsubscribed', {
      contact_id: id,
      email: email,
      timestamp: event.created_at
    });

    // Send confirmation email
    if (!subscribed) {
      await sendEmail({
        to: email,
        subject: 'You have been unsubscribed',
        body: `${first_name}, you've been removed from our mailing list.`
      });
    }
  }
}
Automatically segment contacts when tags change:
async function handleContactUpdated(event) {
  const { id, email, tags, updated_fields } = event.data;

  if (updated_fields.includes('tags')) {
    // Check for specific tag additions
    if (tags.includes('major-donor')) {
      await crm.addToSegment(email, 'Major Donors');
      await sendNotification({
        to: '[email protected]',
        message: `Contact ${email} tagged as major donor`
      });
    }

    if (tags.includes('monthly-giving')) {
      await emailPlatform.addToSequence(email, 'monthly-donor-nurture');
    }
  }
}
Log contact modifications for compliance and reporting:
async function handleContactUpdated(event) {
  const { id, updated_fields, updated_at } = event.data;

  await auditLog.create({
    event_type: 'contact_updated',
    contact_id: id,
    fields_changed: updated_fields,
    timestamp: updated_at,
    source: 'givebutter_webhook'
  });
}

​
Commonly Updated Fields

FieldDescription
emailEmail address changed
phonePhone number added or updated
addressMailing address modified
tagsTags added or removed
subscribedEmail subscription status changed
companyCompany name added or updated

contact.created

New contact was added

transaction.updated

Related transaction was updated