Sync your platform’s users into Touchbase

1. Create your private webhook URL

1. Sign in and open Contacts, then Sources and lists. You can also find Webhook under Integrations → Contact sources.
2. Choose Webhook → Connect (or add another source if one is already connected).
3. Name the list, such as “Website signups”. Under Save contacts under, choose Customers or Investors. Use a separate list and webhook for each group.
4. Choose the statement that describes your relationship with these contacts and confirm it. This is separate from the customer/investor group.
5. Select Make the webhook, then copy the full URL. Save it now: the secret is shown once.

Already created one but lost the URL? Open Contacts → Sources and lists, find the list, and choose New webhook address. Replace the URL in your website or automation; the old URL stops working immediately.

2. Sync existing users, then connect ongoing events

Send an HTTPS POST to the exact URL you copied, with Content-Type: application/json. The secret URL is the credential; no Authorization header is required. Keep it in a server environment variable, not browser JavaScript, a public repository, screenshots, or analytics logs.

For an automation tool, choose an action that sends an HTTP request. Set method to POST, paste the URL, select a JSON body, and map your signup or CRM fields to the fields below. For the first sync, have your platform export or send its existing users in batches (or upload a CSV under Contacts). Then connect signup, profile-update, subscription, and unsubscribe events for ongoing sync. Your platform or connector sends the selected users to the URL; simply saving a URL does not retrieve its historical database.

Replace YOUR_WEBHOOK_SECRET with your real secret, and you@example.com with an email you control. This example adds or updates a contact when you run it; it does not send an email by itself.

curl --request POST 'https://touchbasetechnologies.com/api/hooks/audience/YOUR_WEBHOOK_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
  "event": "user.signed_up",
  "data": {
    "email": "you@example.com",
    "first_name": "Sam",
    "last_name": "Lee",
    "properties": {
      "platform_user_id": "usr_123",
      "plan": "starter",
      "signup_date": "2026-10-29"
    },
    "subscribed": true
  }
}'

// Server-side code only. Save the URL in your hosting environment.
const webhookUrl = process.env.TOUCHBASE_CONTACT_WEBHOOK_URL;

export async function syncContact(user, event = 'user.updated') {
  if (!webhookUrl) throw new Error('Contact webhook URL is missing');
  const response = await fetch(webhookUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      event,
      data: {
        email: user.email,
        first_name: user.firstName,
        last_name: user.lastName,
        properties: { platform_user_id: user.id, plan: user.plan },
        subscribed: user.acceptsMarketing
      }
    })
  });
  const result = await response.json();
  if (!response.ok) throw new Error('Contact sync failed: HTTP ' + response.status);
  // HTTP 200 can still contain rejected rows or skipped contacts.
  if (result.rejected?.length || result.truncated || result.capacitySkipped) {
    throw new Error('Contact sync needs attention; inspect the response counts');
  }
  return result;
}

{
  "contacts": [
    {
      "email": "you@example.com",
      "first_name": "Sam"
    },
    {
      "email": "another@example.com",
      "first_name": "Alex"
    }
  ]
}

{
  "type": "customer.unsubscribed",
  "data": {
    "email": "you@example.com",
    "subscribed": false
  }
}

3. Check the response and find the contact

A successful request returns HTTP 200. For one new contact, the response looks like this:

{
  "added": 1,
  "existing": 0,
  "blocked": 0,
  "optedOut": 0,
  "capacitySkipped": 0,
  "rejected": [],
  "truncated": false
}

• added: new contacts created. existing: contacts already known to this workspace.
• blocked: contacts held back from email, including previous opt-outs or bounces. optedOut: addresses suppressed by this request.
• rejected: unusable rows, with the row number and reason. A 200 response can still include rejected rows.
• truncated: only the first 500 contacts were read. capacitySkipped: new contacts omitted because the list is full. Send only the missing contacts again after resolving the limit.

Open Contacts → Customers or Contacts → Investors, matching the group chosen when creating the URL. Refresh the page, search for the email you sent, and use the list filter if needed. Under Sources and lists, you can also open the list to see its people. An unsubscribe-only event for a new address can suppress it without adding it to the list.

4. Create a campaign or an optional signup reminder

1. Open Outreach → Campaigns and create a campaign.
2. Choose Customers or Investors, then select the webhook’s named list if you want to keep receiving future signups. “All contacts” creates a selection of the contacts available at that time.
3. Choose the email design, edit the subject and content, review the preview, and choose a connected sending mailbox.
4. To send once to each future signup, open the campaign’s New-signup reminders section, set the delay in hours, and choose Save and enable rule. Then review and start the campaign to activate sending. Create another campaign for a later reminder.

New-signup reminders are off until enabled. If you already enabled and started a reminder campaign for this list, incoming contacts can receive that email after its delay. Suppressed, bounced, and otherwise unsendable contacts are excluded. Each reminder is once per future list enrollment, not once per event: sending user.updated repeatedly does not resend that reminder. For another message or audience, configure another campaign/list explicitly.

Troubleshooting

Need help? Contact Touchbase support with the HTTP status, time, and response counts. Remove the secret URL and personal contact data from anything you share.