> For the complete documentation index, see [llms.txt](https://humanic.gitbook.io/humanic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://humanic.gitbook.io/humanic/getting-started-with-humanic/connecting-your-data/connect-using-a-webhook.md).

# 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.

```json
{
  "email": "email@example.com",
  "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`.

```json
{
  "user_id": "user_id_1",
  "event_name": "event_name_1",
  "user_data": {
    "email": "email@example.com",
    "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

```bash
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": "test@yourdomain.com",
      "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](/humanic/getting-started-with-humanic/connecting-your-data/n8n.md) page.

#### Your own backend (Node.js)

```javascript
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).