Articles on: Contacts

Contact Import Webhooks

Contact Import Webhooks


Purpose


Use a team-scoped HTTPS URL to create or update contacts from any system that can send HTTP POST requests with JSON. Ideal for CRMs, form tools, or internal apps pushing one contact (or a batch as a JSON array) into All Contacts without CSV uploads.


Prerequisites


  • Team context: open Contacts (All Contacts) for the team that should own imported profiles.
  • Permission to create contacts (to generate a webhook) and update contacts (to edit mappings and enable/disable webhooks).
  • A sender of test payloads must use JSON whose root is an object or an array of objects with string keys (not arbitrary nested-only blobs without a clear row shape).


Steps


1. Open the webhook flow


  1. Go to Contacts in the sidebar (All Contacts).
  2. Click Add Contact.
  3. Choose Import via Webhook.


2. Create a webhook


  1. In New webhook title, enter a name you will recognize (e.g. CRM sync).
  2. Click Generate Webhook.
  3. SuperSend creates a unique URL. Use Copy next to the URL when you configure the external system.


3. Send a test POST


  1. From your tool or API client, POST sample JSON to the webhook URL.
  2. One contact = one JSON object. Multiple contacts = a JSON array of objects (each item processed as one contact after mapping is saved).
  3. Wait until the UI shows Payload received (or equivalent) for that webhook.


4. Map fields


  1. Click Map Fields on the webhook row (available after at least one payload is stored).
  2. Map incoming JSON keys to SuperSend profile fields.
  3. Map at least one identifier: Email, LinkedIn URL, or Twitter (required for the save to be accepted).
  4. Click Save Mapping when done.


5. Go live


  1. Turn the webhook Active with the toggle if it should accept production traffic.
  2. Keep Inactive while testing if you want to block traffic without deleting the webhook.


Expected Result


  • POSTs to the URL create or update team-level contact profiles according to your mapping.
  • Arrays in one request create/update multiple contacts, one per element, after mapping is saved.
  • You can maintain several webhooks (different URLs/titles) for different sources.


Troubleshooting


  • Issue: Map Fields is disabled or the UI says the payload is not available.

Fix: Send another POST with valid JSON, then open Map Fields again. Root must be an object or array of objects with usable string keys.


  • Issue: Save mapping returns an error about identifiers.

Fix: Map at least one of email, linkedin_url, or twitter to an incoming field.


  • Issue: Requests succeed externally but nothing appears in Contacts.

Fix: Confirm the webhook is Active, mapping is saved, and the team's Contacts page is the correct team. Check permissions if another org member owns the team switcher context.


  • Issue: Wrong or stale field mapping after changing your payload shape.

Fix: Send a new sample that matches production, then adjust mappings; keys must align with what you actually POST.




Updated on: 09/04/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!