HiHello Contacts Webhook

This integration allows you to receive contacts from HiHello into any system using a webhook. This feature is available to all HiHello Enterprise subscribers. HiHello webhooks require an API endpoint. Below, you'll find more information about how the webhook works and a technical guide for setting it up in your HiHello account. 

• Introduction

  • What is a Webhook?

  • How does the HiHello Contacts Webhook work?

  • Setting up the HiHello Contacts Webhook

  • Setting up the HiHello Contacts Webhook

  • Potential use cases for the Contacts Webhook

• Technical Guide

  • Overview

  • How It Works

  • Webhook Requirements

  • Supported Events

  • Setup Guide

Introduction

One of the key values of HiHello is the ability to capture all leads and have them seamlessly show up in your company CRM. For popular platforms like Salesforce, HubSpot, and Microsoft Dynamics, HiHello provides native CRM integrations to streamline this process. If your organization utilizes a proprietary or less commonly used CRM, you can connect it to HiHello using a webhook so that any time a new contact is created, it is immediately sent over to your CRM.

What is a Webhook?

In the simplest terms, a webhook is a way for one app to automatically send information to another app the exact moment something happens. Webhooks are entirely driven by events. When a specific event occurs in the first app, it shoots a message (a webhook) over the internet to the second app signaling that an event just happened.

How does the HiHello Contacts Webhook work?

When a contact is created, updated, or deleted in HiHello, the system automatically sends a notification to the organization's configured webhook URL containing the contact's details — like tags, associated card info, lead capture data, and a timestamp — along with a signature the recipient can use to verify the message genuinely came from HiHello.                                                                                                                      

If your URL responds with a 200 OK to acknowledge receipt then the process ends there. If the delivery fails, the system will retry up to 5 times over the course of a few hours, and every attempt is logged for auditing. There's also a security check that blocks webhook URLs pointing to internal/private network addresses to prevent misuse.

The flowchart below shows the complete workflow for the HiHello Contacts Webhook:

Setting up the HiHello Contacts Webhook

The HiHello Contacts Webhook is for users with knowledge of APIs that need custom workflows created around contact changes in HiHello.

To setup the HiHello Contacts Webhook you must:

• Be on the HiHello Enterprise plan.

• Have an API endpoint (user URL in the diagram above) ready to receive events. HiHello will generate a signing secret. When HiHello sends a webhook, it uses the signing secret to create a fingerprint (HMAC-SHA256) of the message. The API endpoint can do the same math with the same secret and compare results to verify their authenticity. If they match, the message is genuine — not forged by a third party.

• Set up the URL to the API endpoint that will receive the events in HiHello settings.

Potential use cases for the Contacts Webhook

Possibilities are endless and the user can decide what to do with the contact events received. Here are some possible use cases:

• CRM sync — Automatically push new contacts into Salesforce, HubSpot, or a custom CRM when someone exchanges cards.

• Lead routing — Trigger a sales workflow when a contact is created via a lead capture form at an event.

• Email marketing — Add/remove contacts from Mailchimp or similar lists based on tags assigned in HiHello.

• Slack/Teams notifications — Alert a sales channel when a high-value contact is added or tagged.

• Analytics & reporting — Stream contact events into a data warehouse to track networking activity over time.

• Contact deduplication — Detect and merge duplicates in an external system when a contact is created.

• Access provisioning — Automatically grant portal or app access when a contact is added with a specific tag.

• Follow-up automation — Trigger a personalized email or SMS sequence the moment a new contact is created.
   

Technical Guide

Overview

The HiHello Contacts Webhook allows your organization to receive real-time updates whenever contacts are created, updated, or deleted in HiHello. Instead of polling for changes, HiHello pushes contact data directly to your system the moment an event occurs.

This integration is ideal for organizations that:

• Use a custom CRM or internal system
• Need workflows triggered by contact activity
• Want more flexibility than native integrations
   

How It Works

When a contact event occurs in HiHello, the following sequence takes place:

1. A contact is created, updated, or deleted in HiHello.
2. HiHello sends an HTTP POST request to your configured webhook endpoint.
3. Your server receives and processes the JSON payload.
4. Your server responds with HTTP 200 OK to confirm receipt.

If your endpoint does not return a success response, HiHello will retry delivery up to 5 times over several hours. All delivery attempts are logged for auditing purposes. 

Webhook URLs pointing to internal or private network addresses are blocked for security.
 

Webhook Requirements

Supported Events

Setup Guide

Step 1 — Create Your Endpoint

Set up a server endpoint that accepts POST requests, parses JSON payloads, and returns a 200 OK response immediately. Avoid doing heavy processing synchronously — offload to a queue if needed.

Example (Node.js / Express):

Step 2 — Configure Webhook in HiHello

In your HiHello account settings (UI image shown in previous section):

1. Navigate to Settings > Integrations > Webhooks
2. Enter your publicly accessible HTTPS endpoint URL
3. Save the configuration
4. Copy your signing secret — you will need this to verify requests

Step 3 — Verify Webhook Signatures (Recommended)

Each request from HiHello includes two headers used for signature verification:

HiHello signs each payload using HMAC-SHA256 with your signing secret. Use constant-time comparison to prevent timing attacks. Reject requests with a timestamp older than 5 minutes.

Signature verification example (JavaScript):

Simple Payload Example (JSON)

A minimal contact.created event — a contact with only a first name and an email address.

Full Payload Example

A contact.updated event with all fields populated — phones, emails, links, addresses, notes, dates, handles, tags, and lead capture data.

Contact Deleted Behavior and Example

When a contact is deleted, HiHello emits a contact.deleted webhook event.

The delete payload intentionally removes all mutable contact profile data while preserving minimal identifiers required for downstream systems to reconcile the deletion.

Preserved fields

The following fields remain populated after deletion:

• contact_id
• account_id
• organization_id
• card_owner_email
• live_contact
• notes (empty array)
• tags (empty array)
• Event metadata (event, event_id, timestamp, version)

Cleared fields

The following fields are set to null after deletion:

• associated_card_id
• source
• added_at
• updated_at
• card_data
• lead_capture_data

Default values

The following default values are currently observed in delete payloads:

• live_contact: false
• notes: []
• tags: []

Integration guidance

Integrations should use contact_id as the canonical identifier for mapping HiHello contacts to external systems.

Because contact profile data is removed from the delete payload, downstream systems should not rely on fields such as:

• email
• phone number
• name
• associated card ID

Instead, integrations should maintain a persistent mapping between:

• contact_id
• external system record ID

This allows downstream systems to correctly archive, delete, or deactivate the corresponding external record when a contact.deleted event is received.

Example:

Payload Reference

Every webhook POST body is a JSON object. The following tables document every field, its type, presence behavior, and expected values.

Presence legend:

Top-Level Envelope

data Object

data.card_data Object

data.card_data.name Object

data.card_data.fields[] — By Type

type: "phone"

type: "email"

type: "url"

type: "widget"

type: "address"

type: "note"

type: "important_date"

type: "xbox" | "playstation" | "nintendo" | "wechat" | "signal" | "skype" | "zelle"

data.lead_capture_data Object

Only present when the contact was captured via contact exchange with a lead capture form. null otherwise.

The organization configures the lead capture form and its custom fields. card_data contains what the responder fills out about themselves; lead_capture_data.fields contains their responses to the organization's custom questions.

data.lead_capture_data.fields[] Object

Each entry represents a response to one custom question on the lead capture form.

data.notes[] Object

Private notes added by the HiHello user after receiving the contact — e.g. personal observations or follow-up reminders. Not to be confused with type: "note" entries in card_data.fields, which are notes written on the card itself.

data.tags[] Object

Tags applied to the contact. May be empty. Tag names may contain arbitrary text including markdown and auto-generated consent language from lead capture flows.

Accessing Fields in Code

Security Best Practices

• Always verify webhook signatures before processing any payload
• Reject requests with a timestamp older than 5 minutes
• Use HTTPS exclusively — plain HTTP endpoints will not be accepted
• Store your signing secret securely (e.g. environment variable or secrets manager)
• Return 200 OK immediately and process asynchronously

• Use event_id to deduplicate — HiHello may retry if your first response was delayed

   

Troubleshooting

Need Help?

Contact your HiHello Enterprise Account Manager for assistance with setup, debugging, or advanced configuration. Have your organization ID and endpoint URL ready for fastest resolution.