Connect using a WebHook

POST JSON contacts and events to Humanic from any tool or backend.

Humanic's generic webhook accepts an HTTP POST with a JSON body. If your product, database, or automation tool can make an HTTP call, it can send data to Humanic — no native integration required.

Use this for custom backends, internal dashboards, Zapier, Make, n8n, form builders, CRMs, or any in-house system.

If you use PostHog, Shopify, or RudderStack, those have dedicated guides and their own webhook URLs.

---

How it works

Your system / tool / product backend
         ↓
HTTP POST to Humanic webhook URL
  (JSON payload with email + optional event data)
         ↓
Humanic matches or creates a contact
         ↓
Campaigns can fire from the mapped event name
         ↓
Email sends from your configured domain

---

Step 1 — Get your webhook URL

1. In Humanic, go to Integrations → Webhooks

2. Create a webhook (contact upsert or event) and copy the URL

It looks like:

https://prod.humanic.ai/api/webhooks/integrations/[token]

Keep this URL private. Anyone with it can POST data to your workspace. If it is exposed, rotate it from Integrations.

---

Step 2 — Choose a payload shape

You can remap JSON paths in the webhook wizard. The defaults below match what Humanic shows as the sample payload.

Contact upsert (create / update a contact)

Default mapping: email and name at the top level. Extra keys are stored as contact data.

{
  "email": "[e-mail]",
  "name": "User Name",
  "data_field_1": "value_1",
  "data_field_2": "value_2"
}

email is required. Without an event mapping, this updates the contact list (default event name is webhook).

Event (contact + named event)

Default mapping: email/name under user_data, event name at event_name.

{
  "user_id": "user_id_1",
  "event_name": "event_name_1",
  "user_data": {
    "email": "[e-mail]",
    "name": "User Name",
    "data_field_1": "value_1",
    "data_field_2": "value_2"
  },
  "event_data": {
    "data_field_1": "value_1",
    "data_field_2": "value_2"
  }
}

Field	Required	Description
email (or mapped path)	Yes	Used to match or create a contact
event_name	For event webhooks	Campaign trigger name (case-sensitive)
user_id	Optional	Your internal user id
user_data / extra keys	Optional	Contact fields / personalisation tokens
event_data	Optional	Event-specific properties

---

Step 3 — Send a test call

curl -X POST https://prod.humanic.ai/api/webhooks/integrations/[token] \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_id_1",
    "event_name": "user_signed_up",
    "user_data": {
      "email": "[e-mail]",
      "name": "Test User"
    },
    "event_data": {
      "plan": "free"
    }
  }'

A successful call returns HTTP 200. Confirm the event in Integrations on that webhook.

---

Sending from common tools

Zapier

Add a Webhooks by Zapier action. Method POST, paste the Humanic URL, Content-Type: application/json, and map your JSON body.

Make

Add HTTP → Make a Request. Method POST, body type Raw with Content-Type: application/json.

n8n

Use the HTTP Request node. Method POST, body content type JSON. See also the n8n page.

Your own backend (Node.js)

await fetch('https://prod.humanic.ai/api/webhooks/integrations/[token]', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_id: user.id,
    event_name: 'subscription_upgraded',
    user_data: { email: user.email, name: user.name },
    event_data: { plan: newPlan }
  })
});

---

Best practices

• Always include an email (or a mapped path that resolves to one). Without it Humanic cannot attach the event to a contact.

• Use consistent event names (snake_case is the usual convention). Names are case-sensitive.

• Only send fields you will use in email copy or targeting.

• One event per request. For bulk historical imports, use CSV instead.

• The URL is the secret. Do not commit it to a public repo.

---

Troubleshooting

Events aren't appearing — Confirm Content-Type: application/json and that you are posting to the URL shown in Integrations (not an old api.humanic.ai URL).

Contact is created but no email sends — The mapped event name must match a campaign trigger, and your sending domain must be verified.

Fields missing in emails — Token names must match the JSON keys you send (or the paths you mapped in the wizard).